A rulebook for desktop power users
Platform Design macOS is the macos folder of ehmo's platform-design-skills pack. Its SKILL.md converts Apple's Mac guidelines into numbered rules with SwiftUI and AppKit examples across five areas: menu bar, windows, toolbars, sidebars and keyboard, aimed at power users.
The skill states who a Mac app serves: power users who expect deep keyboard control, persistent menu bars, resizable multi-window layouts and tight system integration. Every rule is written against that audience, with SwiftUI and AppKit code.
Rule 1.1 sets the baseline: every app includes App, File, Edit, View, Window and Help menus. File may be omitted only when the app is not document-based, and app-specific menus slot in between.
Five sections, three levels of priority
- Menu bar and Windows are CRITICAL, with six rules each.
- Keyboard is CRITICAL too, anchored by a modifier convention table.
- Toolbars and Sidebars are HIGH, with five rules each.
- Each rule is numbered, so a review can cite Rule 2.6 for traffic lights instead of a vague complaint.
Examples of the rules in practice
Menu items must reflect state: disable what does not apply and retitle for context, so the menu reads Undo Typing rather than a bare Undo. The skill also asks for stable command names and locations.
Windows stay freely resizable with sensible minimums. Traffic light buttons are never hidden or moved. Window position and size persist across launches, using setFrameAutosaveName or SwiftUI state restoration.
Who it suits
Good match
- Developers building macOS apps in SwiftUI or AppKit, or porting from Mac Catalyst.
- Reviews that should catch missing shortcuts, hidden traffic lights or unmovable sidebars.
- Teams whose agent keeps drawing mobile tab bars on desktop windows.
Less useful for
- Tablet and phone screens, which have sibling skills in the same repository.
- Pure visual polish. Related: a polish skill and typography guidance.
Use it with UiChemy
This skill governs native Mac code and does not interact with UiChemy. A product with a Mac app and a WordPress site can design the site in Figma, convert it with UiChemy, and click Get Started on uichemy.com. Related: Apple design guidance and native UI building.
How to install Platform Design macOS: Mac HIG Rules for Coding Agents
git clone https://github.com/ehmo/platform-design-skills.gitClone the pack
Use the command above. The README's one install line is a skills CLI form, which this page avoids in favor of a plain clone.
Lift out skills/macos
That folder carries SKILL.md, AGENTS.md, metadata.json and rules. Copy the whole folder so the agent keeps its references.
Install it in your agent
Place the copy in the directory your agent scans for skills. The pack states no agent folders, so follow your tool's own documentation.
Try a menu review
Ask the agent to check a SwiftUI commands block against the standard menus and shortcut conventions.
Check that it loaded
Give the agent one macOS window and ask for a review. A working install flags missing standard menus, shortcut gaps or toolbar issues using the rule numbers.
Key features
- Six standard menusRule 1.1 requires App, File, Edit, View, Window and Help, and says where app-specific menus belong between them.
- Shortcuts on every actionRule 1.2 gives every action menu item a shortcut, with Cmd plus a letter for custom ones and Cmd+Shift, Cmd+Option or Cmd+Ctrl for secondary actions.
- Dynamic menu stateMenu items disable when not applicable, retitle to match context and toggle checkmarks for on and off states.
- Stable command memoryRule 1.6 treats the menu bar as the app's command memory, keeping common actions in consistent menus with stable names.
- Resizable windowsMain windows are freely resizable with a sensible minimum and no maximum unless the content truly cannot scale.
- Multiple windows and stateNon-utility apps support WindowGroup or DocumentGroup windows, and persist frame and state across launches.
- Traffic lights untouchedClose, minimize and zoom stay in the top-left corner and stay functional even with a custom title bar.
- Customizable toolbarsUsers add, remove and rearrange toolbar items from a superset, and a segmented control switches views such as List, Grid and Column.
- Source list sidebarsThe sidebar sits on the leading edge, collapses, persists its state and uses the sidebar list style with vibrancy and badge counts.
- Modifier convention tableCmd plus letter for primary actions, Cmd+Shift for variants, Cmd+Option for alternatives and Cmd+Ctrl for tertiary actions.
Frequently asked questions
What is the macOS design skill?
It is the macos folder of the platform-design-skills repository, a SKILL.md that distills Apple's Human Interface Guidelines for Mac into numbered rules with SwiftUI and AppKit examples, covering menus, windows, toolbars, sidebars and keyboard interaction.
How do I install the macOS skill?
The README documents a skills CLI command, which this page skips. Clone ehmo/platform-design-skills and copy skills/macos into the folder your agent reads skills from. The pack names no agent folders, so look them up in your agent's docs.
Which standard menus does it require?
App, File, Edit, View, Window and Help. File can be omitted if the app is not document-based. App-specific menus go between Edit and View or between View and Window. Items needing an action must also carry a keyboard shortcut.
How does it handle keyboard shortcuts?
Every action reachable by mouse needs a keyboard equivalent. Primary actions use Cmd plus a letter, secondary ones Cmd+Shift or Cmd+Option, and tertiary ones Cmd+Ctrl. Standard actions such as copy and paste keep their standard shortcuts.
Does it apply to Mac Catalyst?
The frontmatter lists Mac Catalyst among its triggers, and the README's Use when list mentions designing for Catalyst or native macOS. The rules themselves target SwiftUI and AppKit, so test Catalyst projects on a small screen first.
What does it say about sidebars?
Place the sidebar on the leading edge, make it collapsible and persist its collapsed state. Use the sidebar list style for source lists, outline views for hierarchies, drag to reorder, and badge counts for unread or pending items.
Does it work with Claude and other agents?
The README says skills activate automatically when agents detect platform-relevant tasks and lists no specific agents. The folder follows the SKILL.md layout with an AGENTS.md file, so Claude or another agent loading that format should read it.
What license is it under?
The repository is MIT licensed according to GitHub metadata and the README. Keep the license text with any copy you redistribute inside your own repository or hand to a team.