human-interface-guidelines

Human Interface Guidelines

A practical, platform-neutral guide to interface design. It has 18 chapters and about 580 short rules that apply to any product: web pages, dashboards, reports, internal tools, CLIs, and mobile or desktop apps.

Each chapter opens with why the topic matters, meaning what goes wrong for people when it is done badly. Rules follow, grouped by idea, so the guide works both for learning and as a checklist during real work. It also ships as a Claude Code skill, so an AI assistant can apply the same rules while it builds UI for you.

### Errors and empty states
- Place error text next to the problem it describes.
- State how to fix the error ("Use at least 8 characters"), without blame or interjections.
- Give every empty state a clear next action, ideally as a button or link.

Contents

Chapters

How to use it

• To learn: read SKILL.md first, then one chapter at a time. The "Why it matters" line explains the reason behind each group of rules.
• While working: use the 40 core rules in SKILL.md as a checklist, and open the chapter for whatever you are building, such as a form, a table, an alert or a chart.
• With Claude Code: install the skill, described below.

Use as a Claude Code skill

Install it for your user account:

git clone https://github.com/sezaakgun/human-interface-guidelines.git
mkdir -p ~/.claude/skills/human-interface-guidelines
cp human-interface-guidelines/SKILL.md human-interface-guidelines/HIG.md ~/.claude/skills/human-interface-guidelines/

To share it with a team instead, copy the two files into a project repository under .claude/skills/human-interface-guidelines/.

Claude Code picks it up in the next session.

When it runs

• Automatically. Only the skill's one-line description stays in context. Claude loads it when a task involves something people look at or interact with: HTML pages, reports, dashboards, charts, web or native UI, forms, components, error, empty or loading states, UI copy, or a CLI layout.

• On request. Type /human-interface-guidelines, or ask for it by name.

• Every time. Automatic loading depends on the model's judgment and can be missed. To make it certain, add this line to ~/.claude/CLAUDE.md:

  For any HTML page, report, dashboard or UI work, use the human-interface-guidelines skill.
  

How it loads

1. SKILL.md loads first, about 1,600 tokens: the core rules and the HTML house style.
2. When a task touches a specific topic, Claude finds the matching chapter in HIG.md and reads only that part. The full guide is about 16,000 tokens and is never loaded whole.

Sources and approach

This guide is distilled from Apple's Human Interface Guidelines, fetched on 2026-10-13. All 158 content pages were read. The material was then:

• reorganized into its own 18 chapters instead of following the original page structure;
• merged wherever pages repeat the same idea;
• rewritten in original wording;
• generalized: vendor products and platforms are described by what they are (payments, in-car interfaces, wearables, voice assistants), not by name.

Each chapter ends with a Sources: line linking the original pages it draws on. Read those pages for the full detail and images, and for any changes after the fetch date.

Pages left out because they describe vendor programs with no general rule: App Clips, iMessage apps and stickers, Game Center, ShazamKit, ID Verifier, Tap to Pay on iPhone, Live Photos, Mac Catalyst.

Disclaimer

This is an unofficial, independent work. It is not affiliated with, authorized or endorsed by Apple Inc. Apple and Apple product names are trademarks of Apple Inc.

License

The text in this repository is licensed under CC BY 4.0: you may share and adapt it with attribution. The license covers only this repository's own wording, not Apple's original guidelines.