mac-design
Skill1 starsChanged 4 days agoMITView on GitHub
How a desktop app looks and behaves like a real Mac app on macOS 26 and later, in SwiftUI, Electron or Tauri - Apple's principles, the window, sidebar, toolbar, menus, keyboard, type, color, Liquid Glass and dark mode. Use when building or reviewing any Mac window, sidebar, toolbar, menu, panel or Settings screen, or when the user asks for a more native or Apple-like app.
2 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- Stijnus/dsh-rev-engedited, first seen Nov 8, 2026
- daveebbelaar/bamaedited, first seen Nov 1, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 2
- daveebbelaar/bama★ 1.7k24% same
- Stijnus/dsh-rev-eng★ 124% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agents-mdSkill
- app-iconSkill
- buildSkill
- cloneSkill
- debugSkill
- design-systemSkill
- docker-optimizeSkill
- improve-loopSkill
- mac-appSkill
- product-briefSkill
- quality-barSkill
- refactorSkill
- researchSkill
- reviewSkill
- start-hereSkill
- stop-overthinkingSkill
- ui-directorSkill
- user-storiesSkill
- ux-designSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
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
- Distinctive: line 26
Responsibility: ask for permissions at first use, keep data private, guard AI output.
- Distinctive: line 33
Every screen answers: Where am I?
- Very specific: line 37
Before views, write in DESIGN.md at the project root (the file ui-director uses too):
- Distinctive: line 42
Command map: every action, its menu, its shortcut.
- Distinctive: line 62
Only a window whose one job is typing focuses its field.
- Very specific: line 70
Every toolbar button and feature also lives in the menu bar with a shortcut, in Apple's menu order and labels (references/menus.md).
- Distinctive: line 74
Every shortcut shows feedback in the same frame.
- Very specific: line 108
Every surface (each page, the menu bar, each panel, sheet, popover and Settings tab) has been seen in light and dark, as the key window, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
Mac design
The outcome: people use the app for a minute and forget it wasn't made by Apple. Every shortcut they know works, every menu is where they look, and the app still has a character of its own.
Native chrome, creative content. The window frame, menus, keyboard, focus and Settings
follow the platform exactly. The content area (what the app is for) is where the product's own
voice lives: color story, type for headings, how the key object is drawn, motion, empty states.
For the content's direction, use ui-director. For a fully custom set of parts, use
design-system.
The rules here are the same in every stack. How to build them in SwiftUI, Electron or Tauri is in
the mac-app skill. The full checklist with sources: references/rules.md.
Apple's eight principles
The review lens for every screen:
- Purpose: each feature costs people time, attention and trust. Cut what does not earn it.
- Agency: people choose their path. Undo forgives mistakes. No forced tours.
- Responsibility: ask for permissions at first use, keep data private, guard AI output.
- Familiarity: things that look the same work the same. Standard parts, standard symbols.
- Flexibility: keyboard, pointer and resizing all work. People customize what they use daily.
- Simplicity: simple is not minimal. Hierarchy comes from order, space and contrast.
- Craft: instant response, smooth scrolling, aligned edges, layouts that survive resizing.
- Delight: the sum of the other seven, aimed at one feeling. Never decoration added at the end.
Every screen answers: Where am I? What can I do? Where can I go?
Design plan
Before views, write in DESIGN.md at the project root (the file ui-director uses too):
- Archetype: sidebar window, single-window document, menu bar extra, or quick-capture panel. Most personal apps are a sidebar window plus one quick-capture entry point.
- Pages: the sidebar, at most two levels.
- Command map: every action, its menu, its shortcut.
- Empty states: what each page shows before there is data.
- Feeling: the one feeling the app aims for (calm, quick, confident). Motion, words and color reinforce it.
Entry points first
A Mac app is used through its small entry points: a global shortcut, the menu bar, a quick panel, drag and drop, the Share menu. Design those first. A to-do app lives in its quick-add panel. Quick capture is one floating panel, one input, opened by a global shortcut, closed by Escape or Return. On Return, close and show the result at once, save in the background, offer Undo.
The window
- Sidebar, content, detail (inspector). Global actions in the toolbar. No sidebar when navigation is one level. Keep the top area free for dragging the window.
- Toolbar items sit over the column they act on; at most three groups; monochrome symbols, each
with a tooltip; at most one prominent action (Done, Send). Details:
references/toolbars.md. - Window titles name the content ("Today"), not the app.
- Nothing is focused when a window or sheet opens: no focus ring, no cursor, no selected text. Only a window whose one job is typing focuses its field.
- Sheets, popovers and Settings tabs size to their content and scroll only when taller than the screen allows. System scroll bars, never restyled.
- Relaunch restores windows, selection and scroll position. Quit never asks unless typed work would be lost. No splash screen, no onboarding tour.
Menus and keyboard
- Every toolbar button and feature also lives in the menu bar with a shortcut, in Apple's menu
order and labels (
references/menus.md). Items that do not apply are disabled, not hidden. - Standard shortcuts keep their meaning: Command-C, V, X, Z, W, Q, N, comma (Settings).
- Return is the default action, Escape cancels, Delete removes, Space previews, arrows move.
- Every shortcut shows feedback in the same frame. Teach shortcuts in menus and tooltips.
- A context menu on everything people can act on. Undo for every destructive or bulk action.
Look
- Text: macOS sizes, not iOS or web sizes. Body 13 pt, nothing under 10 pt. Headline is bold
13 pt. Full scale:
references/rules.md, rule 29. The system font for UI text; a custom face for headings only, with a reason. - Controls are 22 to 28 pt tall, not 44. Window margins 20 pt, related controls 8 apart, groups 20.
- Color: semantic text colors (primary, secondary, tertiary) and system backgrounds. One accent, by default the one the person chose for their Mac. Status color always with an icon or a word. Text on an accent fill uses an on-accent color, never a fixed white.
- Dark mode is its own palette with more distance between tones. Check both.
- Glass and materials belong to the navigation and control layer (toolbar, sidebar, floating controls), never to rows, cards or documents. Never glass on glass. Electron and Tauri get the system's vibrancy materials, not real Liquid Glass: use them for the sidebar and say so.
- Icons: one set (SF Symbols in SwiftUI; a matching outline set on the web), standard symbols
for standard actions (
references/rules.md, rule 65). - Respect Reduce Motion, Reduce Transparency and Increase Contrast. Label icon-only buttons.
Settings
Command-comma from the app menu. Tabs by topic, one grouped form per tab, applied at once, sized
to its content. Few options. Details: references/settings.md.
When to customize
Custom chrome is fine when it makes the app clearly better at its one job: a quick-add field, a calendar grid, a timeline, a mixer. Match the system around it: concentric radii, system fonts, system spacing, the traffic lights where people expect them.
Done when
Every surface (each page, the menu bar, each panel, sheet, popover and Settings tab) has been
seen in light and dark, as the key window, and every rule in references/rules.md holds or has a
comment saying why not. Look especially for focus rings nobody asked for, scroll bars with
nothing to scroll, and empty bands under short content.
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.

