dickwu/apple-design-skill

Apple Design Skill – AI‑powered UI reviewer for Apple HIG

What it is

• A reusable skill that can be added to AI coding assistants (Claude Code, Cursor, Codex, etc.).
• The skill lets the assistant act as a design reviewer that checks mobile‑ and desktop‑UI code against Apple’s Human Interface Guidelines (HIG).

How it works

• The repository ships a set of 123 Markdown files that are direct copies of the HIG pages (plus a curated “Liquid Glass” guide). Each file retains Apple’s wording, headings, tables and change‑log information.
• A small Node script (scripts/pull‑hig.mjs) can re‑download the latest HIG pages from developer.apple.com, keeping the reference set up‑to‑date.
• When an agent receives a request like “Review my Flutter screen against Apple’s guidelines”, the skill loads the relevant HIG markdown, then produces a structured review:
  1. Apple’s eight design principles
  2. Accessibility checks (text scaling, contrast, control size, etc.)
  3. Platform conventions (tab bars, menus, safe areas, etc.)
  4. Visual design & craft
  5. Interaction patterns
  6. Content & writing style
• Each finding includes What, Why (citing the exact HIG heading), and a Fix written in the framework you’re using (Flutter, React Native, Tauri, Electron, SwiftUI, UIKit, AppKit).
• Special modes handle app‑icon reviews, dark‑mode checks, iPhone Duo dual‑screen layouts, Liquid‑Glass effects, and generative‑AI‑generated UI components.

Installation

• The preferred method is the generic skills CLI:

  npx skills add dickwu/apple-design-skill   # adds to all supported agents
  

• You can target a single agent (-a claude-code, -a cursor, -a codex).
• For Claude Code you can also clone the repo into ~/.claude/skills/apple-design.
• Cursor and other agents read the same .cursorrules / .windsurfrules files that ship with the repo.

Typical usage

Ask your agent:
- "Review my Flutter app's home screen against Apple's guidelines"
- "Audit this Tauri app for accessibility"
- "Does this settings screen follow macOS conventions?"
- "Is my app ready for iPhone Duo's two displays?"
- "Give this generic UI a point of view without breaking iOS patterns"

The agent replies with a bullet‑point review, each item explaining the issue, the HIG reference, and a concrete code‑level fix for the selected framework.

Key components

• SKILL.md – definition of the skill’s stance, lenses, report format, and improvement workflow.
• AGENTS.md – instructions for contributors and for each supported AI agent.
• scripts/pull‑hig.mjs – zero‑dependency Node script that crawls Apple’s JSON API, renders the 123 HIG pages into references/hig/*.md, and updates the routing table.
• references/ – the generated HIG markdown files plus cross‑platform translation tables (cross‑platform.md).

Why it matters

• Saves developers time by automating the tedious, detail‑heavy process of checking UI against Apple’s ever‑changing guidelines.
• Bridges the gap between Apple‑centric design language and cross‑platform UI toolkits (Flutter, React Native, Tauri, Electron, etc.).
• Keeps the reference material fresh with a simple node scripts/pull‑hig.mjs command.

License & provenance

• The guideline text is reproduced from Apple’s public Human Interface Guidelines and is not owned by the project. The skill, script, and curated guide are provided “as‑is” under the repository’s license, with a disclaimer that the project is not affiliated with Apple.

Support

• The author invites sponsorship via GitHub Sponsors to help maintain the HIG‑pull script and keep the skill current.