apple-hig-helper

# Apple Human Interface Guidelines (HIG) Helper

## Overview

The Apple Human Interface Guidelines (HIG) provides comprehensive design guidance for creating great experiences across all Apple platforms. This skill provides access to **174 topics** covering:

- **6 Apple Platforms**: iOS, iPadOS, macOS, tvOS, visionOS, watchOS
- **40+ UI Components**: Buttons, Menus, Alerts, Sheets, Lists, and more
- **20+ Design Patterns**: Navigation, Modality, Feedback, Loading, Settings
- **30+ Apple Technologies**: Apple Pay, Siri, HomeKit, CarPlay, ARKit, HealthKit
- **Design Foundations**: Color, Typography, Icons, Layout, Materials, Branding
- **Accessibility & Inclusion**: Guidelines for building apps everyone can use

**Data Location**: `markdown/`
**Format**: 174 Markdown documentation pages

## Quick Reference: Major Topics with Summaries

### Design Foundations

#### Color

**Path**: `markdown/color/index.md`

Judicious use of color can enhance communication, evoke your brand, provide visual continuity, communicate status and feedback, and help people understand information.

#### Typography

**Path**: `markdown/typography/index.md`

Your typographic choices can help you display legible text, convey an information hierarchy, communicate important content, and express your brand or style.

#### Icons

**Path**: `markdown/icons/index.md`

An effective icon is a graphic asset that expresses a single concept in ways people instantly understand.

#### Layout

**Path**: `markdown/layout/index.md`

A consistent layout that adapts to various contexts makes your experience more approachable and helps people enjoy their favorite apps and games on all their devices.

#### Materials

**Path**: `markdown/materials/index.md`

A material is a visual effect that creates a sense of depth, layering, and hierarchy between foreground and background elements.

#### Branding

**Path**: `markdown/branding/index.md`

Apps and games express their unique brand identity in ways that make them instantly recognizable while feeling at home on the platform and giving people a consistent experience.

#### Dark Mode

**Path**: `markdown/dark-mode/index.md`

Dark Mode is a systemwide appearance setting that uses a dark color palette to provide a comfortable viewing experience tailored for low-light environments.

#### Images

**Path**: `markdown/images/index.md`

To make sure your artwork looks great on all devices you support, learn how the system displays content and how to deliver art at the appropriate scale factors.

### Accessibility & Inclusion

#### Accessibility

**Path**: `markdown/accessibility/index.md`

Accessible user interfaces empower everyone to have a great experience with your app or game.

#### Inclusion

**Path**: `markdown/inclusion/index.md`

Inclusive apps and games put people first by prioritizing respectful communication and presenting content and functionality in ways that everyone can access and understand.

### Common UI Components

#### Buttons

**Path**: `markdown/buttons/index.md`

A button initiates an instantaneous action.

#### Menus

**Path**: `markdown/menus/index.md`

A menu reveals its options when people interact with it, making it a space-efficient way to present commands in your app or game.

#### Alerts

**Path**: `markdown/alerts/index.md`

An alert gives people critical information they need right away.

#### Sheets

**Path**: `markdown/sheets/index.md`

A sheet helps people perform a scoped task that's closely related to their current context.

#### Lists and Tables

**Path**: `markdown/lists-and-tables/index.md`

Lists and tables present data in one or more columns of rows.

#### Pickers

**Path**: `markdown/pickers/index.md`

A picker displays one or more scrollable lists of distinct values that people can choose from.

#### Sliders

**Path**: `markdown/sliders/index.md`

A slider is a horizontal track with a control, called a thumb, that people can adjust between a minimum and maximum value.

#### Toggles

**Path**: `markdown/toggles/index.md`

A toggle lets people choose between a pair of opposing states, like on and off, using a different appearance to indicate each state.

#### Text Fields

**Path**: `markdown/text-fields/index.md`

A text field is a rectangular area in which people enter or edit small, specific pieces of text.

### Design Patterns

#### Modality

**Path**: `markdown/modality/index.md`

Modality is a design technique that presents content in a separate, dedicated mode that prevents interaction with the parent view and requires an explicit action to dismiss.

#### Navigation and Search

**Path**: `markdown/navigation-and-search/index.md`

Help people navigate and find content efficiently.

#### Feedback

**Path**: `markdown/feedback/index.md`

Feedback helps people know what's happening, discover what they can do next, understand the results of actions, and avoid mistakes.

#### Loading

**Path**: `markdown/loading/index.md`

The best content-loading experience finishes before people become aware of it.

#### Settings

**Path**: `markdown/settings/index.md`

People expect apps and games to just work, but they also appreciate having ways to customize the experience to fit their needs.

#### Onboarding

**Path**: `markdown/onboarding/index.md`

Onboarding can help people get a quick start using your app or game.

### Platform-Specific Guidelines

#### Designing for iOS

**Path**: `markdown/designing-for-ios/index.md`

People depend on their iPhone to help them stay connected, play games, view media, accomplish tasks, and track personal data in any location and while on the go.

#### Designing for iPadOS

**Path**: `markdown/designing-for-ipados/index.md`

People value the power, mobility, and flexibility of iPad as they enjoy media, play games, perform detailed productivity tasks, and bring their creations to life.

#### Designing for macOS

**Path**: `markdown/designing-for-macos/index.md`

People rely on the power, spaciousness, and flexibility of a Mac as they perform in-depth productivity tasks, view media or content, and play games, often using several apps at once.

#### Designing for tvOS

**Path**: `markdown/designing-for-tvos/index.md`

People enjoy the vibrant content, immersive experiences, and streamlined interactions that tvOS delivers in media and games, as well as in fitness, education, and home utility apps.

#### Designing for visionOS

**Path**: `markdown/designing-for-visionos/index.md`

When people wear Apple Vision Pro, they enter an infinite 3D space where they can engage with your app or game while staying connected to their surroundings.

#### Designing for watchOS

**Path**: `markdown/designing-for-watchos/index.md`

When people glance at their Apple Watch, they know they can access essential information and perform simple, timely tasks whether they're stationary or in motion.

## Complete Topic Index (All 174 Topics)

### By Category

#### Foundations (9 topics)

- accessibility
- branding
- color
- dark-mode
- icons
- images
- layout
- materials
- typography

#### Components - Content (11 topics)

- activity-rings
- charts
- gauges
- image-views
- labels
- lockups
- progress-indicators
- rating-indicators
- text-views
- web-views
- sf-symbols

#### Components - Layout & Organization (13 topics)

- boxes
- collections
- column-views
- disclosure-controls
- lists-and-tables
- lockups
- outline-views
- scroll-views
- split-views
- tab-views
- tables (see lists-and-tables)
- sidebars
- windows

#### Components - Menus & Actions (11 topics)

- activity-views
- buttons
- context-menus
- controls
- dock-menus
- edit-menus
- home-screen-quick-actions
- menus
- pop-up-buttons
- pull-down-buttons
- segmented-controls

#### Components - Navigation & Search (7 topics)

- navigation-and-search
- page-controls
- path-controls
- search-fields
- searching
- tab-bars
- toolbars

#### Components - Presentation (8 topics)

- action-sheets
- alerts
- panels
- popovers
- sheets
- the-menu-bar
- ornaments
- status-bars

#### Components - Selection & Input (11 topics)

- color-wells
- combo-boxes
- digit-entry-views
- image-wells
- pickers
- sliders
- steppers
- text-fields
- toggles
- token-fields
- virtual-keyboards

#### Components - System Experiences (6 topics)

- complications
- live-activities
- notifications
- top-shelf
- watch-faces
- widgets

#### Patterns (22 topics)

- charting-data
- collaboration-and-sharing
- drag-and-drop
- entering-data
- feedback
- file-management
- going-full-screen
- launching
- live-viewing-apps
- loading
- managing-accounts
- managing-notifications
- modality
- offering-help
- onboarding
- playing-audio
- playing-haptics
- playing-video
- printing
- ratings-and-reviews
- settings
- undo-and-redo
- workouts

#### Inputs (8 topics)

- action-button
- apple-pencil-and-scribble
- camera-control
- digital-crown
- eyes
- focus-and-selection
- game-controls
- gestures
- gyro-and-accelerometer
- keyboards
- nearby-interactions
- pointing-devices
- remotes
- spatial-interactions

#### Technologies (30 topics)

- airplay
- always-on
- app-clips
- app-shortcuts
- apple-pay
- augmented-reality
- carekit
- carplay
- game-center
- generative-ai
- healthkit
- homekit
- icloud
- id-verifier
- imessage-apps-and-stickers
- in-app-purchase
- live-photos
- mac-catalyst
- machine-learning
- maps
- nfc
- photo-editing
- researchkit
- shareplay
- shazamkit
- sign-in-with-apple
- siri
- tap-to-pay-on-iphone
- voiceover
- wallet

#### Platforms (6 topics)

- designing-for-games
- designing-for-ios
- designing-for-ipados
- designing-for-macos
- designing-for-tvos
- designing-for-visionos
- designing-for-watchos

#### Cross-Cutting Concerns (8 topics)

- accessibility
- dark-mode
- inclusion
- immersive-experiences
- motion
- multitasking
- privacy
- right-to-left
- spatial-layout
- writing

### Alphabetical List of All Topics

```
accessibility, action-button, action-sheets, activity-rings, activity-views,
airplay, alerts, always-on, app-clips, app-icons, app-shortcuts, apple-pay,
apple-pencil-and-scribble, augmented-reality, boxes, branding, buttons,
camera-control, carekit, carplay, charting-data, charts,
collaboration-and-sharing, collections, color, color-wells, column-views,
combo-boxes, complications, components, content, context-menus, controls,
dark-mode, designing-for-games, designing-for-ios, designing-for-ipados,
designing-for-macos, designing-for-tvos, designing-for-visionos,
designing-for-watchos, digit-entry-views, digital-crown, disclosure-controls,
dock-menus, drag-and-drop, edit-menus, entering-data, eyes, feedback,
file-management, focus-and-selection, foundations, game-center, game-controls,
gauges, generative-ai, gestures, getting-started, going-full-screen,
gyro-and-accelerometer, healthkit, home-screen-quick-actions, homekit, icloud,
icons, id-verifier, image-views, image-wells, images,
imessage-apps-and-stickers, immersive-experiences, in-app-purchase, inclusion,
inputs, keyboards, labels, launching, layout, layout-and-organization,
lists-and-tables, live-activities, live-photos, live-viewing-apps, loading,
lockups, mac-catalyst, machine-learning, managing-accounts,
managing-notifications, maps, materials, menus, menus-and-actions, modality,
motion, multitasking, navigation-and-search, nearby-interactions, nfc,
notifications, offering-help, onboarding, ornaments, outline-views,
page-controls, panels, path-controls, patterns, photo-editing, pickers,
playing-audio, playing-haptics, playing-video, pointing-devices,
pop-up-buttons, popovers, presentation, printing, privacy, progress-indicators,
pull-down-buttons, rating-indicators, ratings-and-reviews, remotes,
researchkit, right-to-left, scroll-views, search-fields, searching,
segmented-controls, selection-and-input, settings, sf-symbols, shareplay,
shazamkit, sheets, sidebars, sign-in-with-apple, siri, sliders,
spatial-interactions, spatial-layout, split-views, status, status-bars,
steppers, system-experiences, tab-bars, tab-views, tap-to-pay-on-iphone,
technologies, text-fields, text-views, the-menu-bar, toggles, token-fields,
toolbars, top-shelf, typography, undo-and-redo, virtual-keyboards, voiceover,
wallet, watch-faces, web-views, widgets, windows, workouts, writing
```

## Search & Access Patterns

### List All Available Topics

```bash
# List all topic directories
ls markdown/

# Count total topics
ls markdown/ | wc -l

# Search for specific topics
ls markdown/ | grep -i "button"
ls markdown/ | grep -i "menu"
ls markdown/ | grep -i "ios"
```

### Read Topic Metadata (Fast)

Extract title and description without reading full file:

```bash
# Get title
grep -oP '(?<=<title>)[^<]+' markdown/buttons/index.md | head -1

# Get description
grep -oP '(?<=<meta name="description" content=")[^"]+' markdown/buttons/index.md | head -1

# Get both
echo "Title:" && grep -oP '(?<=<title>)[^<]+' markdown/buttons/index.md | head -1
echo "Description:" && grep -oP '(?<=<meta name="description" content=")[^"]+' markdown/buttons/index.md | head -1
```

### Read Full Topic Content

For detailed guidance, read the complete Markdown file:

```bash
# Read entire file (may be large - 50-250KB per file)
cat markdown/buttons/index.md

# Read with Bash tool through Read tool (preferred for large files)
Read markdown/buttons/index.md
```

### Search Across Multiple Topics

```bash
# Extract metadata from multiple related topics
for topic in buttons menus alerts sheets; do
  echo "=== $topic ==="
  grep -oP '(?<=<meta name="description" content=")[^"]+' markdown/$topic/index.md
  echo ""
done

# Search for topics by category
ls markdown/ | grep -E "(button|menu|alert|sheet)"
```

## Usage Examples

### Example 1: "What does HIG say about buttons?"

1. **Quick Summary**: Read the button summary from this skill
2. **Full Details**: `Read markdown/buttons/index.md`
3. **Response**: A button initiates an instantaneous action. (Provide platform-specific guidance from Markdown)

### Example 2: "Show me iOS design guidelines"

1. **Navigate**: `Read markdown/designing-for-ios/index.md`
2. **Summary**: People depend on their iPhone to help them stay connected, play games, view media, accomplish tasks, and track personal data in any location and while on the go.
3. **Provide**: Platform-specific patterns, components, and best practices

### Example 3: "Accessibility best practices from HIG"

1. **Primary Guide**: `Read markdown/accessibility/index.md`
2. **Related Topics**:
   - VoiceOver: `markdown/voiceover/index.md`
   - Inclusion: `markdown/inclusion/index.md`
   - Dynamic Type: Coverage in typography
3. **Summary**: Provide key accessibility principles and implementation guidance

### Example 4: "List all available HIG component topics"

1. **Search**: `ls markdown/ | grep -v "^designing-for" | sort`
2. **Categorize**: Group by component type (layout, navigation, input, etc.)
3. **Provide**: Organized list with brief descriptions

### Example 5: "What technologies does HIG cover?"

**Technologies covered** (30 topics):

- Apple Pay, Siri, HomeKit, CarPlay
- ARKit, HealthKit, SharePlay, Wallet
- Game Center, Maps, Machine Learning
- And 20 more (see Technologies section above)

### Example 6: "How should I design alerts for visionOS?"

1. **Read Alert Guidelines**: `markdown/alerts/index.md`
2. **Read visionOS Platform Guide**: `markdown/designing-for-visionos/index.md`
3. **Cross-reference**: Look for visionOS-specific guidance in alerts Markdown
4. **Provide**: Platform-specific alert design patterns

## Best Practices

### When to Consult HIG

- **Starting a new app or feature**: Review platform guidelines first
- **Implementing standard UI components**: Check component-specific guidance
- **Designing for multiple platforms**: Review each platform's unique patterns
- **Adding Apple technologies**: Consult technology-specific guidelines (Apple Pay, Siri, etc.)
- **Ensuring accessibility**: Review accessibility and inclusion guidelines
- **Resolving design decisions**: HIG provides rationale for Apple's design choices

### How to Use This Skill

1. **Start with the category index** above to find relevant topics
2. **Read metadata summaries** for quick overviews (30 major topics included)
3. **Access full Markdown files** for detailed platform-specific guidance
4. **Cross-reference related topics**:
   - Buttons → Menus → Navigation
   - Color → Dark Mode → Materials
   - Accessibility → VoiceOver → Inclusion
5. **Check platform-specific sections** within component guides

### Navigation Tips

- **Browse by category**: Use the organized lists above (Foundations, Components, Patterns, etc.)
- **Search alphabetically**: Use the complete alphabetical list for quick lookup
- **Follow references**: HIG topics often reference related guidelines
- **Check all platforms**: Some components have platform-specific variations

### Understanding HIG Content

- **Guidelines, not rules**: HIG provides guidance; adapt to your app's needs
- **Platform differences**: iOS, iPadOS, macOS, tvOS, visionOS, and watchOS have unique patterns
- **Context matters**: Consider your app's purpose and user needs
- **Stay updated**: HIG evolves with new OS releases and platform features

## Data Structure Reference

- **Location**: `markdown/`
- **Format**: Markdown files
- **Structure**: `{topic}/index.md` for each topic
- **Metadata**: Available in `<title>` and `<meta>` tags
- **Total Size**: 23 MB (174 files)
- **Index File**: `.visited.json` contains complete list of URLs

## When to Ask for Help

If you need:

- **Comparison across platforms**: "How do alerts differ between iOS and macOS?"
- **Implementation guidance**: "Show me how to implement the button styles from HIG"
- **Design critique**: "Does this design follow HIG principles?"
- **Missing topics**: If a topic isn't in the 174 available, the user may need to check Apple's website
- **Recent updates**: This data was downloaded on a specific date; newest features may require checking Apple's site

---

**Quick Start**: Ask "What does HIG say about [topic]?" or "Show me [platform] design guidelines" to get started!