agentleFS
aka-kikaaka-kika/akakika-skills/skills/apple-hig/apple-hig-macos-window-layout/SKILL.md

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.

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
  1. Distinctive:

    Use this skill when designing or implementing the overall macOS app window shell: titlebar, toolbar, sidebar, content area, inspector, …

    line 12
  2. Distinctive:

    Do not use for:

    line 37
  3. Distinctive:

    Use minimum sizes so layout does not break.

    line 73
  4. Distinctive:

    Use native toolbar when possible.

    line 127
  5. Distinctive:

    Do not fake the macOS titlebar unless required.

    line 128
  6. Distinctive:

    Keep toolbar actions contextual.

    line 129
  7. Distinctive:

    Search may belong in toolbar if central.

    line 132
  8. Distinctive:

    Use sheets for short focused tasks:

    line 136
  9. Distinctive:

    Use separate windows for:

    line 145
  10. Distinctive:

    Do not put complex multi-step workflows in tiny popovers.

    line 162
  11. Distinctive:

    Ensure sidebar can collapse.

    line 168
  12. Distinctive:

    Ensure inspector can hide.

    line 169
  13. Distinctive:

    Avoid fixed layouts that break when resized.

    line 170
  14. Distinctive:

    If the app has both a menu bar item and a full window:

    line 175
  15. Distinctive:

    Do not duplicate the full app inside the menu bar popover.

    line 182
  16. Distinctive:

    Avoid too many borders.

    line 191
  17. Distinctive:

    Avoid heavy glass everywhere.

    line 192

≈ “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.

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

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 px

Window size guidance

Small utility:       520 × 420
Medium productivity: 900 × 640
Large workspace:     1100 × 720+
Settings:            520–640 × 360–520
Menu bar popover:    320–420 wide

Use 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 export

Use separate windows for:

Settings
Detailed logs
Large editor
Long report preview

Use popovers for:

Small contextual controls
Quick capture
Short menu bar interactions

Do 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 workspace

Do 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 possible

Common 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-like

Prompt 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.

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.