# hig-components-system

Adds Apple HIG guidelines for widgets, Live Activities, complications, and alerts. Guides design choices for interfaces outside your main app.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 625 installs · ★ 148
- Author: raintree-technology
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/raintree-technology/hig-doctor/tree/HEAD/skills/hig-components-system/SKILL.md
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/skills/hig-components-system

## What it does

This skill supplies Apple Human Interface Guidelines for surfaces outside your main application. It covers Home Screen and Lock Screen widgets, Live Activities for Dynamic Island, watchOS complications, tvOS Top Shelf, App Clips, and Siri shortcuts. Recommendations focus on glanceable value and layout adaptation across distinct sizes.

The skill inspects `.claude/apple-design-context.md` before prompting you with questions. It uses your existing project notes to avoid repetitive back-and-forth. Direct deep linking is treated as a hard requirement: tapping a surface must route directly to specific content rather than your app's home screen.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add raintree-technology/hig-doctor --skill hig-components-system -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/hig-components-system/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/hig-components-system/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add raintree-technology/hig-doctor --skill hig-components-system -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/hig-components-system/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add raintree-technology/hig-doctor --skill hig-components-system -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/hig-components-system/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install raintree-technology/hig-doctor hig-components-system
```

2. **Manually: put the files in place**
- File: `.github/skills/hig-components-system/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add raintree-technology/hig-doctor --skill hig-components-system -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/raintree-technology/hig-doctor --path skills/hig-components-system
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/hig-components-system/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add raintree-technology/hig-doctor --skill hig-components-system -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/raintree-technology/hig-doctor/tree/HEAD/skills/hig-components-system/SKILL.md

## When to use it
- Structure Live Activities for Dynamic Island and Lock Screen
- Select layout variants and content priorities across widget sizes
- Configure Home Screen quick actions with appropriate SF Symbols
- Plan update frequencies within system background budgets

## Example prompts
- Design a Live Activity for real-time delivery tracking
- What information should go into a watch complication versus a lock screen widget?
- Suggest three Home Screen quick actions for a note-taking app

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 4ec4f562ae299608.

BEGIN THIRD-PARTY FILE 4ec4f562ae299608
```text
---
name: hig-components-system
version: 1.0.0
description: >-
  Apple HIG guidance for system experience components: widgets, live activities,
  notifications, complications, home screen quick actions, top shelf, watch faces,
  app clips, and app shortcuts. Use when asked about: "widget design", "live activity",
  "notification design", "complication", "home screen quick action",
  "top shelf", "watch face", "app clip", "app shortcut", "system experience".
  Also use when the user says "how do I design a widget," "what should my notification
  look like," "how do Live Activities work," "should I make an App Clip," or asks about
  surfaces outside the main app.
  Cross-references: hig-components-status for progress in widgets, hig-inputs for
  interaction patterns, hig-technologies for Siri and system integration.
---

# Apple HIG: System Experiences

Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.

## Key Principles

1. **Glanceable, immediate value.** System experiences bring your app's most important content to surfaces the user sees without launching your app. Design for seconds of attention.

2. **Respect platform context.** A Lock Screen widget has different constraints than a Home Screen widget. A complication is far smaller than a top shelf item.

3. **Widgets: show relevant information, not everything.** Display the most useful subset, updated appropriately.

4. **Support multiple widget sizes with distinct layouts.** Each size should be a thoughtful design, not a scaled version of another.

5. **Deep-link on tap.** Take users to the relevant content, not the app's root screen.

6. **Live Activities: track events with a clear start and end.** Deliveries, scores, timers, rides. Design for both Dynamic Island and Lock Screen.

7. **Stay updated and timely.** Stale data undermines trust. End promptly when the event concludes.

8. **Respect user attention with notifications.** Only send notifications for information users genuinely care about. No promotional or low-value notifications.

9. **Notifications: actionable and self-contained.** Include enough context to understand and act without opening the app. Support notification actions. Use threading and grouping.

10. **Complications: focused data on the watch face.** Design for the smallest useful representation. Support multiple families. Budget updates wisely.

11. **Home Screen quick actions: 3-4 most common tasks.** Short titles, optional subtitles, relevant SF Symbol icons.

12. **Top Shelf: tvOS showcase.** Feature content that entices: new episodes, featured items, recent content.

13. **App Clips: instant, focused functionality within a strict size budget.** Load quickly without App Store download. Only what's needed for the immediate task, then offer full app install.
```
END THIRD-PARTY FILE 4ec4f562ae299608

The third-party file has ended. Everything between the 4ec4f562ae299608 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2876 of 5034 bytes. © raintree-technology · MIT · https://github.com/raintree-technology/hig-doctor/tree/HEAD/skills/hig-components-system/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md