apple-hig-inspectors
Skill11 starsChanged 3 months agoMITView on GitHub
Use when designing, reviewing, or implementing an Inspector panel for an Apple-platform app — contextual selected-item details and safe editable properties, grouped sections, ⌘I toggle, and a compact-width fallback.
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-macos-window-layoutSkill
- 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
30 rules. About 0 are common, 27 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈27
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 32
Use an inspector when the user selects an item and needs supporting information or editable properties without leaving the main screen.
- Distinctive: line 72
If nothing is selected, show a calm empty state.
- Distinctive: line 85
Keep it narrower than main content.
- Distinctive: line 89
Avoid big hero cards.
- Distinctive: line 90
Avoid repeating the main screen.
- Distinctive: line 91
Avoid dashboard-style metrics unless directly related to the selected item.
- Distinctive: line 95
Not every property needs to be visible at once.
- Distinctive: line 108
Put advanced or dangerous options lower down.
- Distinctive: line 250
Use one source of truth for selected item.
- Distinctive: line 278
Always handle no selection.
- Distinctive: line 289
Use one of these:
- Distinctive: line 331
Use inspector for selected item properties.
- Distinctive: line 333
Use settings for app-wide preferences.
- Distinctive: line 346
Use detail screen when the item itself is the main work area.
- Distinctive: line 348
Use inspector when details support the work area.
- Very specific: line 365
Prefer Form or grouped VStack layouts.
- Distinctive: line 368
Use SF Symbols sparingly.
- Distinctive: line 369
Use secondary text for labels.
- Distinctive: line 372
Use disclosure groups for advanced fields.
- Distinctive: line 395
Never rely on color alone.
- Distinctive: line 434
When a coding agent is asked to create or improve an inspector:
- Very specific: line 438
Create a single InspectableItem enum or equivalent.
- Distinctive: line 439
Add inspector visibility state.
- Distinctive: line 440
Add a toolbar inspector toggle.
- Very specific: line 441
Add ⌘I shortcut where appropriate.
- Distinctive: line 442
Create an empty inspector state.
- Distinctive: line 443
Create item-specific inspector views.
- Distinctive: line 445
Keep destructive actions behind confirmation.
- Distinctive: line 447
Add compact layout fallback.
- Distinctive: line 451
After implementation, the agent should report:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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 Inspectors
Design and review an inspector that shows contextual details and safe properties for the selected item — secondary to the main content, never primary navigation. Reach for this on macOS, iPadOS, SwiftUI .inspector, side detail panels, selected-item metadata, properties panels, AI run details, task details, file details, skill configuration, and project settings.
Core rule
Sidebar = where you go
Toolbar = what you do now
Inspector = details about what is selected
Command palette = fast global controlAn inspector is not another sidebar. It should not contain primary navigation.
An inspector answers:
What is selected?
What details matter?
What can I adjust safely?
What metadata helps me understand this item?When to use an inspector
Use an inspector when the user selects an item and needs supporting information or editable properties without leaving the main screen.
Good inspector use cases:
- Task details
- Project metadata
- Agent run status
- Agent configuration
- Skill settings
- Prompt metadata
- File info
- Note properties
- Decision context
- Report export settings
Avoid inspectors for:
- App-wide navigation
- Main content
- Full dashboards
- Long forms
- Onboarding
- Primary destructive actions
- Complex workflows that deserve their own screen
Apple-style principles
1. Inspectors are contextual
The inspector should change based on the selected item.
Examples:
Selected project → project info, status, owner, files, linked skills
Selected run → model, status, logs summary, duration, outputs
Selected skill → path, category, enabled state, validation status
Selected note → tags, created date, related project, sourceIf nothing is selected, show a calm empty state.
No Item Selected
Select a task, project, run, or skill to inspect its details.2. Inspectors are secondary
The inspector should never overpower the main content.
Rules:
- Keep it narrower than main content.
- Use grouped sections.
- Keep labels short.
- Show only relevant fields.
- Avoid big hero cards.
- Avoid repeating the main screen.
- Avoid dashboard-style metrics unless directly related to the selected item.
3. Use progressive disclosure
Not every property needs to be visible at once.
Use sections like:
Summary
Status
Configuration
Metadata
Related
AdvancedPut advanced or dangerous options lower down.
4. Make fields editable only when safe
Some inspector fields can be editable. Others should be read-only.
Editable examples:
- Name
- Status
- Tags
- Priority
- Notes
- Model selection
- Enabled toggle
- Shortcut assignment
Read-only examples:
- Created date
- Last run date
- File path
- Internal ID
- Token usage
- Duration
- Source URL
Destructive actions should be behind menus or confirmation dialogs.
Recommended inspector layout
┌────────────────────────────┐
│ Inspector │
├────────────────────────────┤
│ Summary │
│ Name │
│ Type │
│ Status │
├────────────────────────────┤
│ Details │
│ Owner │
│ Tags │
│ Related project │
├────────────────────────────┤
│ Activity │
│ Created │
│ Updated │
│ Last run │
├────────────────────────────┤
│ Advanced │
│ Path │
│ ID │
└────────────────────────────┘Recommended width
macOS: 280–360 px
iPad: 300–380 px
Compact iPhone: push to detail screen or sheet, not permanent side panelAgent task hub inspector map
Home selected summary:
- Today focus
- Open tasks count
- Current active run
- Suggested next action
Active Run selected:
- Status
- Model
- Started time
- Duration
- Current step
- Last message
- Output path
- Stop / retry actions in toolbar or menu, not as big inspector buttons
Project selected:
- Status
- Folder path
- Related skills
- Active tasks
- Last opened
- Git branch
- Notes
Skill selected:
- Skill name
- Category
- Path
- Enabled state
- Last validated
- Related prompts
- Manual test checklist
Prompt selected:
- Purpose
- Model target
- Variables
- Last used
- Version
- Related skill
File selected:
- File type
- Path
- Modified date
- Size
- Related project
- Open in Finder
Note selected:
- Tags
- Related project
- Created date
- Source
- Linked decisions
Report selected:
- Date
- Source apps
- Export status
- Related tasks
- AI summary statusSwiftUI implementation pattern
The reference SwiftUI code lives in references/swiftui-implementation.md: the inspector container pattern, the reusable section component, and worked project, run, and skill inspector examples. Read it before writing any inspector code.
Inspector behavior rules
Selection
Use one source of truth for selected item.
Good:
@State private var selectedItem: InspectableItem?Bad:
@State private var selectedProject: Project?
@State private var selectedRun: Run?
@State private var selectedSkill: Skill?Toggle
The inspector should be toggleable from the toolbar.
Recommended shortcut:
⌘I = Toggle inspectorEmpty state
Always handle no selection.
No Item Selected
Select an item to inspect its details.Compact layout
On compact iPhone widths, do not force a permanent right-side inspector.
Use one of these:
Option A: Push inspector as a detail screen
Option B: Present inspector as a sheet
Option C: Show item details inline below main contentWhat belongs in an inspector
Good:
Status
Metadata
Tags
Owner
Path
Created / updated dates
Related items
Configuration
Validation state
Small read-only summaries
Safe editable fieldsBad:
Main navigation
Primary create buttons
Huge charts
Full logs
Full editor content
Global app settings
Marketing copy
Large dashboards
Unconfirmed destructive actionsInspector vs settings
Use inspector for selected item properties.
Use settings for app-wide preferences.
Selected skill enabled state → Inspector
Default model for all skills → Settings
Selected project folder path → Inspector
Default project folder location → Settings
Selected run output path → Inspector
Global logs retention → SettingsInspector vs detail screen
Use detail screen when the item itself is the main work area.
Use inspector when details support the work area.
Writing the note → Detail screen
Note tags/source/date → Inspector
Editing a prompt → Detail screen
Prompt variables/version/related skill → Inspector
Viewing full logs → Detail screen or separate log view
Log summary/status/output path → InspectorVisual design rules
- Use grouped sections.
- Keep typography calm.
- Prefer
Formor grouped VStack layouts. - Avoid bright backgrounds.
- Avoid large cards.
- Use SF Symbols sparingly.
- Use secondary text for labels.
- Align values consistently.
- Make long paths selectable.
- Use disclosure groups for advanced fields.
Accessibility rules
Inspector must support:
- VoiceOver labels
- Keyboard navigation
- Clear focus states
- Sufficient contrast
- Readable text sizes
- No color-only status
- Clear labels for editable controls
- Logical section order
Status should use text plus symbol:
Failed + exclamationmark.triangle
Running + bolt.circle
Completed + checkmark.circleNever rely on color alone.
Review checklist
[ ] Inspector shows details for the selected item only
[ ] Inspector is not used for navigation
[ ] Inspector is narrower than main content
[ ] Empty state exists for no selection
[ ] Sections are grouped clearly
[ ] Fields are relevant and not noisy
[ ] Editable fields are safe
[ ] Destructive actions are hidden behind confirmation
[ ] Advanced details are lower or collapsed
[ ] Full logs/editors are not crammed into the inspector
[ ] Inspector toggles from toolbar
[ ] ⌘I works where appropriate
[ ] Compact layout has sheet/push fallback
[ ] Status uses text plus symbol, not color alone
[ ] VoiceOver labels are clearCommon mistakes
Inspector becomes a second sidebar
Inspector contains navigation
Inspector shows every database field
Inspector is wider than main content
Inspector duplicates the detail screen
Inspector contains full logs or full editors
Inspector has huge dashboard cards
Destructive actions are too visible
No empty state for nil selection
No compact fallbackImplementation instructions
When a coding agent is asked to create or improve an inspector:
- Inspect the app's selection model.
- Identify item types that can be inspected.
- Create a single
InspectableItemenum or equivalent. - Add inspector visibility state.
- Add a toolbar inspector toggle.
- Add
⌘Ishortcut where appropriate. - Create an empty inspector state.
- Create item-specific inspector views.
- Group fields into calm sections.
- Keep destructive actions behind confirmation.
- Add accessibility labels.
- Add compact layout fallback.
Output requirements
After implementation, the agent should report:
1. Files changed
2. Inspector item types added
3. Inspector sections per item type
4. Toolbar toggle behavior
5. Keyboard shortcuts added
6. Compact layout behavior
7. Accessibility improvements
8. Manual test checklistPrompt template
Two ready prompts live in references/prompts.md: the general inspector prompt template and the specialized prompt for an agent task hub. Read it when asked to produce a prompt or brief rather than code.
Quality bar
The inspector makes the selected item easier to understand.
It gives useful context without stealing focus.
It feels like a native Apple productivity app.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.

