agentleFS
aka-kikaaka-kika/akakika-skills/skills/apple-hig/apple-hig-inspectors/SKILL.md

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.

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

    Use an inspector when the user selects an item and needs supporting information or editable properties without leaving the main screen.

    line 32
  2. Distinctive:

    If nothing is selected, show a calm empty state.

    line 72
  3. Distinctive:

    Keep it narrower than main content.

    line 85
  4. Distinctive:

    Avoid big hero cards.

    line 89
  5. Distinctive:

    Avoid repeating the main screen.

    line 90
  6. Distinctive:

    Avoid dashboard-style metrics unless directly related to the selected item.

    line 91
  7. Distinctive:

    Not every property needs to be visible at once.

    line 95
  8. Distinctive:

    Put advanced or dangerous options lower down.

    line 108
  9. Distinctive:

    Use one source of truth for selected item.

    line 250
  10. Distinctive:

    Always handle no selection.

    line 278
  11. Distinctive:

    Use one of these:

    line 289
  12. Distinctive:

    Use inspector for selected item properties.

    line 331
  13. Distinctive:

    Use settings for app-wide preferences.

    line 333
  14. Distinctive:

    Use detail screen when the item itself is the main work area.

    line 346
  15. Distinctive:

    Use inspector when details support the work area.

    line 348
  16. Very specific:

    Prefer Form or grouped VStack layouts.

    line 365
  17. Distinctive:

    Use SF Symbols sparingly.

    line 368
  18. Distinctive:

    Use secondary text for labels.

    line 369
  19. Distinctive:

    Use disclosure groups for advanced fields.

    line 372
  20. Distinctive:

    Never rely on color alone.

    line 395
  21. Distinctive:

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

    line 434
  22. Very specific:

    Create a single InspectableItem enum or equivalent.

    line 438
  23. Distinctive:

    Add inspector visibility state.

    line 439
  24. Distinctive:

    Add a toolbar inspector toggle.

    line 440
  25. Very specific:

    Add ⌘I shortcut where appropriate.

    line 441
  26. Distinctive:

    Create an empty inspector state.

    line 442
  27. Distinctive:

    Create item-specific inspector views.

    line 443
  28. Distinctive:

    Keep destructive actions behind confirmation.

    line 445
  29. Distinctive:

    Add compact layout fallback.

    line 447
  30. Distinctive:

    After implementation, the agent should report:

    line 451

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

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

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.

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.