Cue_Space / apple-design
AGENTS.md3 starsChanged 34 days agoMITView on GitHub
Operating manual for AI agents working in this repository, or using it from another project. Apple Design Skill: a design-review skill (SKILL.md) backed by 123 pages of Apple's Human Interface Guidelines pulled from developer.apple.com into references/hig/, one curated guide, a generated lookup table, and the script that regenerates all of it. 1. Read SKILL.md in full. It defines the reviewer's stance, Apple's eight design principles, the five audit lenses, the report format, and the improvement process. 2. Open references/hig-lookup.md to…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- bragSkill
- brag-slimSkill
- apple-designSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Read SKILL.md in full. It defines the reviewer's stance, Apple's eight design principles, the five audit lenses, the report format, and the …
- Very specific: line 23
Write the report in the SKILL.md format: Summary, Critical, Improvements, Craft notes, What works, Platform notes.
- Very specific: line 69
After running it: review git diff --stat, spot-check a changed file, run the checks below, refresh liquid-glass.md if a page it links to …
- Very specific: line 89
Keep SKILL.md under about 400 lines.
- Very specific: line 92
Don't add pages to references/hig/ by hand.
- Distinctive: line 97
Commit generated changes separately from hand-written changes.
- Very specific: line 98
Do not commit .cache/, .omc/, or other local state.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Operating manual for AI agents working in this repository, or using it from another project.
What this repository is
Apple Design Skill: a design-review skill (SKILL.md) backed by 123 pages of Apple's Human
Interface Guidelines pulled from developer.apple.com into references/hig/, one curated guide,
a generated lookup table, and the script that regenerates all of it.
Running a design review
- Read
SKILL.mdin full. It defines the reviewer's stance, Apple's eight design principles, the five audit lenses, the report format, and the improvement process. - Open
references/hig-lookup.mdto route a topic to a file. It is grouped by Apple's sections and carries Apple's one-line summary of every page. - Load the always-load set (
accessibility.md,layout.md,typography.md,color.md, plusdesigning-for-ios.mdordesigning-for-macos.md, plusreferences/cross-platform.mdunless the app is SwiftUI, UIKit, or AppKit) and 3 to 6 more files for what is on screen. Never load the whole directory. - Quote the guideline and cite it as
file.md › Heading. Use the user's framework vocabulary (Flutter, React Native, Tauri, Electron, SwiftUI, UIKit, AppKit). - Write the report in the
SKILL.mdformat: Summary, Critical, Improvements, Craft notes, What works, Platform notes. Each finding has a What, a Why with a citation, and a Fix.
File map
| Path | Role | Edit by hand? |
SKILL.md | The skill: stance, principles, lenses, report format, improvement mode | Yes |
AGENTS.md | This file | Yes |
README.md | Installation and overview for people | Yes |
.cursorrules | Entry point for Cursor | Yes |
.github/FUNDING.yml | GitHub Sponsors button configuration | Yes |
references/hig-lookup.md | Generated routing table with an omitted-pages list | No, re-run the script |
references/hig/*.md | 123 generated pages in Apple's wording | No, re-run the script |
references/hig/liquid-glass.md | Curated Liquid Glass guide; the script never touches it | Yes |
references/cross-platform.md | Apple's vocabulary and conventions for Flutter, React Native, Tauri, and Electron | Yes |
scripts/pull-hig.mjs | Pull script, Node 18 or newer, no dependencies | Yes |
Refreshing the references
node scripts/pull-hig.mjs # pull from developer.apple.com into references/
node scripts/pull-hig.mjs --cache .cache # also keep the raw JSON for fast re-runsOptions: --out <dir>, --lookup <file>, --cache <dir>, --concurrency <n>, --no-prune,
--force-prune.
What the script does:
- Crawls Apple's six HIG sections and their sub-collections (158 pages as of September 2026).
- Keeps every page that applies to iOS, iPadOS, or macOS, omits Apple-only hardware and services
listed in
OMITTED_PAGES, and records every omission with a reason inhig-lookup.md. - Renders Apple's JSON to Markdown faithfully: headings, paragraphs, lists, tables, notes, and tabbed content as sub-headings. Images and videos are dropped except for check-mark glyphs in comparison tables.
- Relabels platform headings by device class (
Phone (iOS),Tablet (iPadOS),Mobile (iOS, iPadOS),Desktop (macOS), and combinations), drops sections that apply only to tvOS, visionOS, or watchOS (sentences that mention them stay), and rewrites cross-references as local links whose anchors match the relabeled headings. Links to headings that were dropped or that Apple no longer publishes point at the file instead. - Keeps each page's change log and turns Apple's "Related" links into a "Related guidelines" list.
- Prunes generated files for pages Apple removed. Curated files are never pruned, and a run
that would prune more than a tenth of the files stops and asks for
--force-prune.
After running it: review git diff --stat, spot-check a changed file, run the checks below,
refresh liquid-glass.md if a page it links to changed, and update the page counts in
README.md, SKILL.md, and this file if the file count changed. A new "Designing for" page has
no platform metadata: if its Platforms covered line doesn't name a platform, add its slug to
DESIGNING_FOR_COVERAGE in the script.
Checks before finishing any change
node --check scripts/pull-hig.mjs
node scripts/pull-hig.mjs --cache .cache && git status --short # second run must change nothing
grep -rl 'doc://' references/hig # must print nothing
npx skills add . --list # must find the apple-design skillAlso confirm that every guideline file named in SKILL.md exists in references/hig/. Ignore
the file.md placeholder in the report template and hig-lookup.md, which lives one level up.
Conventions
- Keep
SKILL.mdunder about 400 lines. It loads in full every time the skill triggers. - Apple's text in
references/hig/is quoted, not paraphrased. Cross-platform translation lives inreferences/cross-platform.md,SKILL.md, andliquid-glass.md, not in the pulled files. - Don't add pages to
references/hig/by hand. ChangeOMITTED_PAGESor the platform rule in the script instead. - A hand-written file in
references/hig/must be registered inCURATED_FILESand must not start with the generated header (a> Source: <...>line followed by> Section:). Open it with> Curated guideasliquid-glass.mddoes, so prune can never mistake it for output. - Commit generated changes separately from hand-written changes.
- Do not commit
.cache/,.omc/, or other local state.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

