agentleFS
Sign inStart free
ehmoehmo/platform-design-skills/skills/macos/AGENTS.md

platform-design-skills / macos

AGENTS.md603 starsChanged 8 months agoMITView on GitHub

This skill provides Apple Human Interface Guidelines for macOS. Apply these rules when building, reviewing, or designing Mac apps using SwiftUI or AppKit. Rules marked CRITICAL must never be skipped. Rules marked HIGH should be followed unless there is a documented reason. Rules marked MEDIUM are strong recommendations.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

14 rules. About 0 are common, 11 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read SKILL.md for the full rule set with code examples

    line 18
  2. Very specific:

    Read rules/_sections.md for the categorized quick-reference

    line 19
  3. Very specific:

    Use the evaluation checklist in SKILL.md before shipping

    line 20
  4. Distinctive:

    Every destructive action needs Cmd+Z undo

    line 45
  5. Distinctive:

    Never ship without a menu bar

    line 53
  6. Distinctive:

    Never use hamburger menus — use the menu bar or a sidebar

    line 54
  7. Distinctive:

    Never place a tab bar at the bottom of the screen

    line 55
  8. Distinctive:

    Never hardcode colors — use semantic system colors for Dark Mode compatibility

    line 56
  9. Distinctive:

    Never build non-resizable main windows

    line 57
  10. Distinctive:

    Never omit keyboard shortcuts for common actions

    line 58
  11. Distinctive:

    Never block full keyboard navigation — no keyboard traps

    line 59
  12. Distinctive:

    Never override traffic light buttons or window chrome

    line 60
  13. Distinctive:

    Never use floating action buttons — use toolbar and menu bar actions

    line 61
  14. Distinctive:

    Never ignore VoiceOver — every control needs an accessibility label

    line 62

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

macOS Design Guidelines — Agent Instructions

Purpose

This skill provides Apple Human Interface Guidelines for macOS. Apply these rules when building, reviewing, or designing Mac apps using SwiftUI or AppKit.

When to Apply

  • Building any macOS application
  • Reviewing Mac UI code or designs
  • Implementing menu bars, toolbars, sidebars, or window management
  • Adding keyboard shortcuts or pointer interactions
  • Porting iOS apps to Mac via Catalyst or Designed for iPad
  • Evaluating desktop app usability

How to Use

  1. Read SKILL.md for the full rule set with code examples
  2. Read rules/_sections.md for the categorized quick-reference
  3. Use the evaluation checklist in SKILL.md before shipping

Priority

Rules marked CRITICAL must never be skipped. Rules marked HIGH should be followed unless there is a documented reason. Rules marked MEDIUM are strong recommendations.

Rule Categories

#CategoryImpact
1Menu BarCRITICAL
2WindowsCRITICAL
3ToolbarsHIGH
4SidebarsHIGH
5KeyboardCRITICAL
6Pointer and MouseHIGH
7Notifications and AlertsMEDIUM
8System IntegrationMEDIUM
9Visual DesignHIGH
10PopoversMEDIUM
11AccessibilityCRITICAL

Key Principles

  • Mac users expect menu bars, keyboard shortcuts, and multi-window support
  • Every destructive action needs Cmd+Z undo
  • Toolbars and sidebars should be user-customizable
  • Respect system appearance (Dark Mode, accent color, font size)
  • Support drag and drop everywhere it makes sense
  • Desktop apps are power-user tools — don't hide functionality behind discoverability walls

Never Do

  • Never ship without a menu bar
  • Never use hamburger menus — use the menu bar or a sidebar
  • Never place a tab bar at the bottom of the screen
  • Never hardcode colors — use semantic system colors for Dark Mode compatibility
  • Never build non-resizable main windows
  • Never omit keyboard shortcuts for common actions
  • Never block full keyboard navigation — no keyboard traps
  • Never override traffic light buttons or window chrome
  • Never use floating action buttons — use toolbar and menu bar actions
  • Never ignore VoiceOver — every control needs an accessibility label

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free