apple-hig-macos-window-layout
Skill11 starsChanged 3 months agoMITView on GitHub
Use when designing or implementing the overall macOS app window shell — titlebar, toolbar, sidebar, content, inspector, window sizing, panels, sheets, and menu bar companion windows.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-empty-statesSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-search-filteringSkill
- apple-hig-settingsSkill
- apple-hig-sf-symbolsSkill
- apple-hig-sidebarsSkill
- apple-hig-toolbarsSkill
- apple-hig-typographySkill
- blog-post-publishingSkill
- social-post-kitSkill
- color-principlesSkill
- kika-design-systemSkill
- emergency-switch-appSkill
- product-hunt-polish-reviewSkill
- docs-updateSkill
- project-folder-cleanupSkill
- between-runs-auditSkill
- explain-new-projectSkill
- new-project-gateSkill
- old-project-auditSkill
- project-catch-upSkill
- project-workflowSkill
- project-worth-my-timeSkill
- butterfly-effectSkill
- spreadSkill
- tilSkill
- apple-app-intentsSkill
- macos-app-distribution-dmgSkill
- macos-clipboard-pasteboardSkill
- macos-global-shortcutsSkill
- macos-launch-at-loginSkill
- macos-menubar-swiftuiSkill
- macos-notificationsSkill
- macos-permissions-privacySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
17 rules. About 0 are common, 17 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when designing or implementing the overall macOS app window shell: titlebar, toolbar, sidebar, content area, inspector, …
- Distinctive: line 37
Do not use for:
- Distinctive: line 73
Use minimum sizes so layout does not break.
- Distinctive: line 127
Use native toolbar when possible.
- Distinctive: line 128
Do not fake the macOS titlebar unless required.
- Distinctive: line 129
Keep toolbar actions contextual.
- Distinctive: line 132
Search may belong in toolbar if central.
- Distinctive: line 136
Use sheets for short focused tasks:
- Distinctive: line 145
Use separate windows for:
- Distinctive: line 162
Do not put complex multi-step workflows in tiny popovers.
- Distinctive: line 168
Ensure sidebar can collapse.
- Distinctive: line 169
Ensure inspector can hide.
- Distinctive: line 170
Avoid fixed layouts that break when resized.
- Distinctive: line 175
If the app has both a menu bar item and a full window:
- Distinctive: line 182
Do not duplicate the full app inside the menu bar popover.
- Distinctive: line 191
Avoid too many borders.
- Distinctive: line 192
Avoid heavy glass everywhere.
≈ “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
Apple HIG macOS Window Layout
Build a stable, resizable, native macOS window shell organized around the main task: titlebar, toolbar, sidebar, content, inspector, sizing, panels, sheets, and menu bar companions. Reach for it when shaping the overall window structure rather than one isolated component.
Purpose
Use this skill when designing or implementing the overall macOS app window shell: titlebar, toolbar, sidebar, content area, inspector, window sizing, panels, sheets, and menu bar companion windows.
Core rule
A macOS window should feel stable, resizable, native, and organized around the main task.When to use this skill
Use for:
- Main macOS app windows
- Utility windows
- Menu bar companion windows
- Split view layout
- Sidebar + detail + inspector
- Toolbar placement
- Window sizing
- Settings window sizing
- Floating panels
- Sheets
When not to use this skill
Do not use for:
- iPhone layout only
- Typography only
- Sidebar content only
- Menu bar popover only
Standard productivity window
┌─────────────────────────────────────────────┐
│ Toolbar / titlebar │
├──────────────┬───────────────────┬──────────┤
│ Sidebar │ Main Content │ Inspector│
│ │ │ │
└──────────────┴───────────────────┴──────────┘Recommended widths:
Sidebar: 220–280 px
Main: flexible, dominant
Inspector: 280–360 pxWindow size guidance
Small utility: 520 × 420
Medium productivity: 900 × 640
Large workspace: 1100 × 720+
Settings: 520–640 × 360–520
Menu bar popover: 320–420 wideUse minimum sizes so layout does not break.
SwiftUI window setup
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
RootWindowView()
.frame(minWidth: 900, minHeight: 640)
}
Settings {
SettingsView()
.frame(width: 560, height: 420)
}
}
}Root window pattern
struct RootWindowView: View {
@State private var selection: SidebarDestination? = .home
@State private var showsInspector = true
var body: some View {
NavigationSplitView {
SidebarView(selection: $selection)
} detail: {
DetailView(selection: selection)
.inspector(isPresented: $showsInspector) {
InspectorPanel()
.inspectorColumnWidth(min: 280, ideal: 320, max: 380)
}
}
.toolbar {
ToolbarItem(placement: .primaryAction) {
Button {
showsInspector.toggle()
} label: {
Label("Inspector", systemImage: "sidebar.right")
}
.keyboardShortcut("i", modifiers: [.command])
}
}
}
}Titlebar and toolbar rules
- Use native toolbar when possible.
- Do not fake the macOS titlebar unless required.
- Keep toolbar actions contextual.
- Sidebar toggle belongs in toolbar/navigation area.
- Inspector toggle belongs in trailing toolbar.
- Search may belong in toolbar if central.
Sheets vs windows vs popovers
Use sheets for short focused tasks:
New Project
Rename
Choose template
Confirm exportUse separate windows for:
Settings
Detailed logs
Large editor
Long report previewUse popovers for:
Small contextual controls
Quick capture
Short menu bar interactionsDo not put complex multi-step workflows in tiny popovers.
Resizing rules
- Define minimum width/height.
- Test narrow widths.
- Ensure sidebar can collapse.
- Ensure inspector can hide.
- Avoid fixed layouts that break when resized.
- Avoid full-screen-only assumptions.
macOS menu bar companion rule
If the app has both a menu bar item and a full window:
Menu bar = quick status / quick capture / quick action
Window = full workspaceDo not duplicate the full app inside the menu bar popover.
Visual rules
- Main content dominates.
- Sidebar is calm.
- Toolbar is quiet.
- Inspector is secondary.
- Window should have clear hierarchy.
- Avoid too many borders.
- Avoid heavy glass everywhere.
- Use material sparingly.
Review checklist
[ ] Window has a clear main task
[ ] Sidebar/content/inspector roles are clear
[ ] Toolbar actions are contextual
[ ] Window has useful minimum size
[ ] Layout survives resizing
[ ] Sidebar can collapse
[ ] Inspector can hide
[ ] Settings window is appropriately sized
[ ] Complex workflows are not inside tiny popovers
[ ] Native macOS chrome is preserved where possibleCommon mistakes
Fake custom titlebar for no reason
Full dashboard inside menu bar popover
No minimum window size
Inspector always visible on tiny width
Toolbar used as navigation
Sidebar too wide
Content squeezed by too many panels
Settings window too large or dashboard-likePrompt template
Use the apple-hig-macos-window-layout skill to improve the macOS window shell.
Rules:
- Preserve native macOS window behavior.
- Use NavigationSplitView for sidebar/content layouts.
- Use inspector for selected-item details.
- Keep main content dominant.
- Add sensible minimum window size.
- Make sidebar collapsible.
- Make inspector toggleable.
- Use sheets for short focused tasks.
- Use windows for large workflows.
- Do not duplicate full app inside menu bar popover.
- Test resizing.
After coding:
1. List files changed.
2. Explain window layout.
3. Explain sizing decisions.
4. Explain sidebar/inspector behavior.
5. Give manual test steps.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.

