Apple Hig Inspectors

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 control

An 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, source

If 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
Advanced

Put 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 panel

Agent 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 status

SwiftUI 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 inspector

Empty 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 content

What belongs in an inspector

Good:

Status
Metadata
Tags
Owner
Path
Created / updated dates
Related items
Configuration
Validation state
Small read-only summaries
Safe editable fields

Bad:

Main navigation
Primary create buttons
Huge charts
Full logs
Full editor content
Global app settings
Marketing copy
Large dashboards
Unconfirmed destructive actions

Inspector 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 → Settings

Inspector 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 → Inspector

Visual design rules

• Use grouped sections.
• Keep typography calm.
• Prefer Form or 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.circle

Never 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 clear

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

Implementation instructions

When a coding agent is asked to create or improve an inspector:

1. Inspect the app's selection model.
2. Identify item types that can be inspected.
3. Create a single InspectableItem enum or equivalent.
4. Add inspector visibility state.
5. Add a toolbar inspector toggle.
6. Add ⌘I shortcut where appropriate.
7. Create an empty inspector state.
8. Create item-specific inspector views.
9. Group fields into calm sections.
10. Keep destructive actions behind confirmation.
11. Add accessibility labels.
12. 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 checklist

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