@ngxtm/devkit 3.15.0 → 3.17.0

package/merged-commands/hig-components-dialogs.md

@@ -0,0 +1,81 @@
+---
+name: hig-components-dialogs
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for presentation components including alerts, action sheets,
+  popovers, sheets, and digit entry views. Use this skill when the user says
+  "should I use an alert or a sheet," "how do I show a confirmation dialog,"
+  "when should I use a popover," "my modals are annoying users," or asks about
+  alert design, action sheet, popover, sheet, modal, dialog, digit entry,
+  confirmation dialog, warning dialog, modal presentation, non-modal content,
+  destructive action confirmation, or overlay UI patterns. Cross-references:
+  hig-components-menus, hig-components-controls, hig-components-search,
+  hig-patterns.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Presentation Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Alerts: sparingly, for critical situations.** Errors needing attention, destructive action confirmations, or information requiring acknowledgment. They interrupt flow and demand a response.
+
+2. **Sheets: focused tasks that maintain context.** Slides in from the edge (or attaches to a window on macOS). Use for creating items, editing settings, multi-step forms.
+
+3. **Popovers: non-modal on iPad and Mac.** Appear next to the trigger element, dismissed by tapping outside. For additional information, options, or controls without taking over the screen.
+
+4. **Action sheets: choosing among actions.** Present when picking from multiple actions, especially if one is destructive. iPhone: slide up from bottom. iPad: appear as popovers.
+
+5. **Minimize interruptions.** Before reaching for a modal, consider inline presentation or making the action undoable instead.
+
+6. **Concise, actionable alert text.** Short descriptive title. Brief message body if needed. Button labels should be specific verbs ("Delete", "Save"), not "OK".
+
+7. **Mark destructive actions clearly.** Destructive button style (red text). Place destructive buttons where users are less likely to tap reflexively.
+
+8. **Provide a cancel option** for alerts and action sheets with multiple actions. On action sheets, cancel appears at the bottom, separated.
+
+9. **Digit entry: focused and accessible.** Appropriately sized input fields, automatic advancement between digits, support for paste and autofill.
+
+10. **Adapt presentation to platform.** The same interaction may use different components on iPhone, iPad, Mac, and visionOS.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [alerts.md](references/alerts.md) | Alerts | Button ordering, title/message text, confirmation, destructive actions |
+| [action-sheets.md](references/action-sheets.md) | Action sheets | Multiple actions, cancel option, destructive handling |
+| [popovers.md](references/popovers.md) | Popovers | Non-modal, dismiss on tap outside, iPad/Mac |
+| [sheets.md](references/sheets.md) | Sheets | Modal task, context preservation |
+| [digit-entry-views.md](references/digit-entry-views.md) | Digit entry | PIN input, autofill, auto-advance |
+
+## Output Format
+
+1. **Recommended presentation type with rationale** and why alternatives are less suitable.
+2. **Content guidelines** -- title, message, button labels per Apple's tone and brevity rules.
+3. **Dismiss behavior** -- how the user dismisses and what happens (save, discard, cancel).
+4. **Alternatives** -- when the scenario might not need a modal at all (inline feedback, undo, progressive disclosure).
+
+## Questions to Ask
+
+1. What information or action does the presentation need?
+2. Blocking or non-blocking?
+3. Which platforms?
+4. How often does this appear?
+
+## Related Skills
+
+- **hig-components-menus** -- Buttons and toolbar items triggering presentations
+- **hig-components-controls** -- Input controls within sheets and popovers
+- **hig-components-search** -- Search and navigation within presented views
+- **hig-patterns** -- Modality, interruptions, user flow management
+- **hig-foundations** -- Color, typography, layout for presentation components
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-layout.md

@@ -0,0 +1,104 @@
+---
+name: hig-components-layout
+version: 1.0.0
+description: ">"
+  Apple Human Interface Guidelines for layout and navigation components. Use this skill when the user
+  asks about "sidebar", "split view", "tab bar", "tab view", "scroll view", "window design", "panel",
+  "list view", "table view", "column view", "outline view", "navigation structure", "app layout",
+  "boxes", "ornaments", or organizing content hierarchically in Apple apps.
+  Also use when the user says "how should I organize my app", "what navigation pattern should I use",
+  "my layout breaks on iPad", "how do I build a sidebar", "should I use tabs or a sidebar",
+  or "my app doesn't adapt to different screen sizes".
+  Cross-references: hig-foundations for layout/spacing principles, hig-platforms for platform-specific
+  navigation, hig-patterns for multitasking and full-screen, hig-components-content for content display.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Layout and Navigation Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Organize hierarchically.** Structure information from broad categories to specific details. Sidebars for top-level sections, lists for browsable items, detail views for individual content.
+
+2. **Use standard navigation patterns.** Tab bars for flat navigation between peer sections (iPhone). Sidebars for deep hierarchical navigation (iPad, Mac). Match the pattern to the information architecture and platform.
+
+3. **Adapt to screen size.** Three-column on iPad collapses to single-column on iPhone. Use size classes and adaptive APIs (NavigationSplitView) for automatic adaptation.
+
+4. **Support multitasking on iPad.** Respond gracefully to Split View, Slide Over, and Stage Manager. Test at every split ratio and size class transition.
+
+5. **Maintain spatial consistency on visionOS.** Windows, volumes, and ornaments in shared space. Position predictably. Use ornaments for toolbars and controls without occluding content.
+
+6. **Use scroll views for overflow content.** Enable paging for discrete content units. Support pull-to-refresh where appropriate. Respect safe areas.
+
+7. **Keep navigation predictable.** Users should always know where they are, how they got there, and how to go back. Use back buttons, breadcrumbs, and clear section titles.
+
+8. **Prefer system components.** UINavigationController, UISplitViewController, NavigationSplitView, and TabView provide built-in adaptivity, accessibility, and state restoration.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [sidebars.md](references/sidebars.md) | Sidebars | Source lists, selection state, collapsible sections, iPad/Mac patterns |
+| [column-views.md](references/column-views.md) | Column Views | Finder-style browsing, progressive disclosure through columns |
+| [outline-views.md](references/outline-views.md) | Outline Views | Expandable hierarchies, disclosure triangles, tree structures |
+| [split-views.md](references/split-views.md) | Split Views | Two/three column layouts, NavigationSplitView, adaptive collapse |
+| [tab-views.md](references/tab-views.md) | Tab Views | Segmented tabs, page-style tabs, macOS tab grouping |
+| [tab-bars.md](references/tab-bars.md) | Tab Bars | Bottom tab bars (iOS), badge counts, max tab count |
+| [scroll-views.md](references/scroll-views.md) | Scroll Views | Paging, scroll indicators, content insets, pull-to-refresh |
+| [windows.md](references/windows.md) | Windows | macOS/visionOS window management, sizing, full-screen, restoration |
+| [panels.md](references/panels.md) | Panels | Inspector panels, utility panels, floating panels, macOS conventions |
+| [lists-and-tables.md](references/lists-and-tables.md) | Lists and Tables | Plain/grouped/inset-grouped styles, swipe actions, section headers |
+| [boxes.md](references/boxes.md) | Boxes | Content grouping containers, labeled boxes, macOS grouping |
+| [ornaments.md](references/ornaments.md) | Ornaments | visionOS toolbar attachments, positioning, visibility |
+
+## Navigation Pattern Selection
+
+| App Structure | Recommended Pattern | Platform Adaptation |
+|---|---|---|
+| 3-5 peer top-level sections | Tab Bar | iPhone: bottom tab bar. iPad: sidebar (`.sidebarAdaptable`, iPadOS 18+). Mac: sidebar or toolbar tabs |
+| Deep hierarchical content | Sidebar + NavigationSplitView | iPhone: single column stack. iPad: two/three columns. Mac: full multi-column |
+| Deep file/folder tree | Column View | Mac: Finder-style. iPad: adaptable. iPhone: push navigation |
+| Flat list with detail | Split View (two column) | iPhone: push/pop stack. iPad/Mac: primary + detail columns |
+| Document-based with inspectors | Window + Panels | Mac: main window with inspector. iPad: sheet or popover |
+| Spatial app with tools | Window + Ornaments | visionOS: ornaments on window. Other platforms: toolbars |
+
+## Layout Adaptation Checklist
+
+- [ ] **Compact width (iPhone portrait):** Navigation collapses to single stack? Tab bars visible?
+- [ ] **Regular width (iPad landscape, Mac):** Navigation expands to sidebar + detail? Space used well?
+- [ ] **Multitasking (iPad):** Adapts at every split ratio? Works in Slide Over?
+- [ ] **Accessibility:** Supports Dynamic Type at all sizes? VoiceOver order logical?
+- [ ] **Orientation:** Content reflows between portrait and landscape?
+- [ ] **visionOS:** Windows positioned ergonomically? Ornaments accessible? Depth meaningful?
+
+## Output Format
+
+1. **Recommended navigation pattern** with rationale for the app's information architecture.
+2. **Layout hierarchy** from root container down (e.g., TabView > NavigationSplitView > List > Detail).
+3. **Platform adaptation** across targeted platforms and size classes.
+4. **Size class behavior** at each transition.
+
+## Questions to Ask
+
+1. What is the app's information architecture? (Sections, hierarchy depth, top-level categories?)
+2. How many top-level sections?
+3. Which platforms?
+4. Need multitasking on iPad?
+5. SwiftUI or UIKit?
+
+## Related Skills
+
+- **hig-foundations** -- Layout spacing, margins, safe areas, alignment
+- **hig-platforms** -- Platform-specific navigation conventions
+- **hig-patterns** -- Multitasking, full-screen, and launching patterns
+- **hig-components-content** -- Content displayed within layout containers
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-menus.md

@@ -0,0 +1,86 @@
+---
+name: hig-components-menus
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for menu and button components including menus, context menus,
+  dock menus, edit menus, the menu bar, toolbars, action buttons, pop-up buttons,
+  pull-down buttons, disclosure controls, and standard buttons. Use this skill
+  when the user says "how should my buttons look," "what goes in the menu bar,"
+  "should I use a context menu or action sheet," "how do I design a toolbar," or
+  asks about button design, menu design, context menu, toolbar, menu bar, action
+  button, pop-up button, pull-down button, disclosure control, dock menu, edit
+  menu, or any menu/button component layout and behavior. Cross-references:
+  hig-components-search, hig-components-controls, hig-components-dialogs.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Menus and Buttons
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Menus should be contextual and predictable.** Standard items in standard locations. Follow platform conventions for ordering and grouping.
+
+2. **Use standard button styles.** System-defined styles communicate affordance and maintain visual consistency. Prefer them over custom designs.
+
+3. **Toolbars for frequent actions.** Most commonly used commands in the toolbar. Rarely used actions belong in menus.
+
+4. **Menu bar is the primary command interface on macOS.** Every command reachable from the menu bar. Toolbars and context menus supplement, not replace.
+
+5. **Context menus for secondary actions.** Right-click or long-press, relevant to the item under the pointer. Never put a command only in a context menu.
+
+6. **Pop-up buttons for mutually exclusive choices.** Select exactly one option from a set.
+
+7. **Pull-down buttons for action lists.** No current selection; they offer a set of commands.
+
+8. **Action buttons consolidate related actions** behind a single icon in toolbars or title bars.
+
+9. **Disclosure controls for progressive disclosure.** Show or hide additional content.
+
+10. **Dock menus: short and focused** on the most useful actions when the app is running.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [menus.md](references/menus.md) | General menu design | Item ordering, grouping, shortcuts |
+| [context-menus.md](references/context-menus.md) | Context menus | Right-click, long press, secondary actions |
+| [dock-menus.md](references/dock-menus.md) | Dock menus | macOS app-level actions, running state |
+| [edit-menus.md](references/edit-menus.md) | Edit menus | Undo, copy, paste, standard items |
+| [the-menu-bar.md](references/the-menu-bar.md) | Menu bar | macOS primary command interface, structure |
+| [toolbars.md](references/toolbars.md) | Toolbars | Frequent actions, customization, placement |
+| [buttons.md](references/buttons.md) | Buttons | System styles, sizing, affordance |
+| [action-button.md](references/action-button.md) | Action button | Grouped secondary actions, toolbar use |
+| [pop-up-buttons.md](references/pop-up-buttons.md) | Pop-up buttons | Mutually exclusive choice selection |
+| [pull-down-buttons.md](references/pull-down-buttons.md) | Pull-down buttons | Action lists, no current selection |
+| [disclosure-controls.md](references/disclosure-controls.md) | Disclosure controls | Progressive disclosure, show/hide |
+
+## Output Format
+
+1. **Component recommendation** -- which menu or button type and why.
+2. **Visual hierarchy** -- placement, sizing, grouping within the interface.
+3. **Platform-specific behavior** across iOS, iPadOS, macOS, visionOS.
+4. **Keyboard shortcuts** (macOS) -- standard and custom shortcuts for menu items and toolbar actions.
+
+## Questions to Ask
+
+1. Which platforms?
+2. Primary or secondary action?
+3. How many actions need to be available?
+4. macOS menu bar app?
+
+## Related Skills
+
+- **hig-components-search** -- Search fields, page controls alongside toolbars and menus
+- **hig-components-controls** -- Toggles, pickers, segmented controls complementing buttons
+- **hig-components-dialogs** -- Alerts, sheets, popovers triggered by menu items or buttons
+- **hig-inputs** -- Keyboard shortcuts and pointer interactions with menus and toolbars
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-search.md

@@ -0,0 +1,73 @@
+---
+name: hig-components-search
+version: 1.0.0
+description: ">-"
+  Apple HIG guidance for navigation-related components including search fields,
+  page controls, and path controls. Use this skill when the user says "how should
+  search work in my app," "I need a breadcrumb," "how do I paginate content," or
+  asks about search field, search bar, page control, path control, breadcrumb,
+  navigation component, search UX, search suggestions, search scopes, paginated
+  content navigation, or file path hierarchy display. Cross-references:
+  hig-components-menus, hig-components-controls, hig-components-dialogs,
+  hig-patterns.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Navigation Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Search: discoverable with instant feedback.** Place search fields where users expect them (top of list, toolbar/navigation bar). Show results as the user types.
+
+2. **Page controls: position in a flat page sequence.** For discrete, equally weighted pages (onboarding, photo gallery). Show current page and total count.
+
+3. **Path controls: file hierarchy navigation.** macOS path controls display location within a directory structure and allow jumping to any ancestor.
+
+4. **Search scopes narrow large result sets.** Provide scope buttons so users can filter without complex queries.
+
+5. **Clear empty states for search.** Helpful message suggesting corrections or alternatives, not a blank screen.
+
+6. **Page controls are not for hierarchical navigation.** Flat, linear sequences only. Use navigation controllers, tab bars, or sidebars for hierarchy.
+
+7. **Keep path controls concise.** Show meaningful segments only. Users can click any segment to navigate directly.
+
+8. **Support keyboard for search.** Command-F and system search shortcuts should activate search.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [search-fields.md](references/search-fields.md) | Search fields | Scopes, tokens, instant results, placement |
+| [page-controls.md](references/page-controls.md) | Page controls | Dot indicators, flat page sequences |
+| [path-controls.md](references/path-controls.md) | Path controls | Breadcrumbs, ancestor navigation |
+
+## Output Format
+
+1. **Component recommendation** -- search field, page control, or path control, and why.
+2. **Behavior specification** -- interaction model (search-as-you-type, swipe for pages, click-to-navigate for paths).
+3. **Platform differences** across iOS, iPadOS, macOS, visionOS.
+
+## Questions to Ask
+
+1. What type of content is being searched or navigated?
+2. Which platforms?
+3. How large is the dataset?
+4. Is search the primary interaction?
+
+## Related Skills
+
+- **hig-components-menus** -- Toolbars and menu bars hosting search and navigation controls
+- **hig-components-controls** -- Text fields, pickers, segmented controls in search interfaces
+- **hig-components-dialogs** -- Popovers and sheets for expanded search or filtering
+- **hig-patterns** -- Navigation patterns and information architecture
+- **hig-foundations** -- Typography and layout for navigation components
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-status.md

@@ -0,0 +1,91 @@
+---
+name: hig-components-status
+version: 1.0.0
+description: ">"
+  Apple HIG guidance for status and progress UI components including progress indicators,
+  status bars, and activity rings. Use this skill when asked about: "progress indicator",
+  "progress bar", "loading spinner", "status bar", "activity ring", "progress display",
+  determinate vs indeterminate progress, loading states, or fitness tracking rings.
+  Also use when the user says "how do I show loading state," "should I use a spinner
+  or progress bar," "what goes in the status bar," or asks about activity indicators.
+  Cross-references: hig-components-system for widgets and complications,
+  hig-inputs for gesture-driven progress controls, hig-technologies for HealthKit
+  and activity ring data integration.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Status Components
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+### Progress Indicators
+
+1. **Show progress for operations longer than a second or two.**
+
+2. **Determinate when duration/percentage is known.** A filling progress bar gives users a clear sense of remaining work. Use for downloads, uploads, or any measurable process.
+
+3. **Indeterminate when duration is unknown.** A spinner communicates work is happening without promising a timeframe. Use for unpredictable network requests.
+
+4. **Prefer progress bars over spinners.** Determinate progress feels faster and more trustworthy.
+
+5. **Place indicators where content will appear.** Inline progress near the content area, not modal or distant.
+
+6. **Don't stack multiple indicators.** Aggregate simultaneous operations into one representation or show the most relevant.
+
+### Status Bars
+
+7. **Don't hide the status bar without good reason.** Reserve hiding for immersive experiences (full-screen media, games, AR).
+
+8. **Match status bar style to your content.** Light or dark for adequate contrast.
+
+9. **Respect safe areas.** No interactive content behind the status bar.
+
+10. **Restore promptly** when exiting immersive contexts.
+
+### Activity Rings
+
+11. **Activity rings are for Move, Exercise, and Stand goals.** Don't repurpose the ring metaphor for unrelated data.
+
+12. **Respect ring color conventions.** Red (Move), green (Exercise), blue (Stand) are strongly associated with Apple Fitness.
+
+13. **Use HealthKit APIs** for activity data rather than manual tracking.
+
+14. **Celebrate completions** with animation and haptics when rings close.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [progress-indicators.md](references/progress-indicators.md) | Progress bars and spinners | Determinate, indeterminate, inline placement, duration |
+| [status-bars.md](references/status-bars.md) | iOS/iPadOS status bar | System info, visibility, style, safe areas |
+| [activity-rings.md](references/activity-rings.md) | watchOS activity rings | Move/Exercise/Stand, HealthKit, fitness tracking, color |
+
+## Output Format
+
+1. **Indicator type recommendation** with rationale (determinate vs indeterminate).
+2. **Timing and animation guidance** -- duration thresholds, animation style, transitions.
+3. **Accessibility** -- VoiceOver progress announcements, live region updates.
+4. **Platform-specific behavior** across targeted platforms.
+
+## Questions to Ask
+
+1. Is the duration known or unknown?
+2. Which platforms?
+3. How long does the operation typically take?
+4. System-level or in-app indicator?
+
+## Related Skills
+
+- **hig-components-system** -- Widgets and complications displaying progress or status
+- **hig-inputs** -- Gestures triggering progress states (pull-to-refresh)
+- **hig-technologies** -- HealthKit for activity ring data; VoiceOver for progress announcements
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-components-system.md

@@ -0,0 +1,111 @@
+---
+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.
+risk: unknown
+source: community
+---
+
+# 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
+
+### General
+
+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.
+
+### Widgets
+
+3. **Show relevant information, not everything.** Display the most useful subset, updated appropriately.
+
+4. **Support multiple 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.
+
+### Live Activities
+
+6. **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.
+
+### Notifications
+
+8. **Respect user attention.** Only send notifications for information users genuinely care about. No promotional or low-value notifications.
+
+9. **Actionable and self-contained.** Include enough context to understand and act without opening the app. Support notification actions. Use threading and grouping.
+
+### Complications
+
+10. **Focused data on the watch face.** Design for the smallest useful representation. Support multiple families. Budget updates wisely.
+
+### Home Screen Quick Actions
+
+11. **3-4 most common tasks.** Short titles, optional subtitles, relevant SF Symbol icons.
+
+### Top Shelf
+
+12. **tvOS showcase.** Feature content that entices: new episodes, featured items, recent content.
+
+### App Clips
+
+13. **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.
+
+### App Shortcuts
+
+14. **Surface key actions to Siri and Spotlight.** Define shortcuts for frequent tasks. Use natural, conversational trigger phrases.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [widgets.md](references/widgets.md) | Widgets | Glanceable info, sizes, deep linking, timeline |
+| [live-activities.md](references/live-activities.md) | Live Activities | Real-time tracking, Dynamic Island, Lock Screen |
+| [notifications.md](references/notifications.md) | Notifications | Attention, actions, grouping, content |
+| [complications.md](references/complications.md) | Complications | Watch face data, families, budgeted updates |
+| [home-screen-quick-actions.md](references/home-screen-quick-actions.md) | Quick actions | Haptic Touch, common tasks, SF Symbols |
+| [top-shelf.md](references/top-shelf.md) | Top shelf | Featured content, showcase |
+| [app-clips.md](references/app-clips.md) | App Clips | Instant use, lightweight, focused task, NFC/QR |
+| [watch-faces.md](references/watch-faces.md) | Watch faces | Custom complications, face sharing |
+| [app-shortcuts.md](references/app-shortcuts.md) | App Shortcuts | Siri, Spotlight, voice triggers |
+
+## Output Format
+
+1. **System experience recommendation** -- which surface best fits the use case.
+2. **Content strategy** -- what to display, priority, what to omit.
+3. **Update frequency** -- refresh rate including system budget constraints.
+4. **Size/family variants** -- which to support and how layout adapts.
+5. **Deep link behavior** -- where tapping takes the user.
+
+## Questions to Ask
+
+1. What information needs to surface outside the app?
+2. Which platform?
+3. How frequently does the data update?
+4. What is the primary glanceable need?
+
+## Related Skills
+
+- **hig-components-status** -- Progress indicators in widgets or Live Activities
+- **hig-inputs** -- Interaction patterns for system experiences (Digital Crown for complications)
+- **hig-technologies** -- Siri for App Shortcuts, HealthKit for complications, NFC for App Clips
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/hig-foundations.md

@@ -0,0 +1,103 @@
+---
+name: hig-foundations
+version: 1.0.0
+description: ">"
+  Apple Human Interface Guidelines design foundations. Use this skill when the user asks about
+  "HIG color", "Apple typography", "SF Symbols", "dark mode guidelines", "accessible design",
+  "Apple design foundations", "app icon", "layout guidelines", "materials", "motion", "privacy",
+  "right to left", "RTL", "inclusive design", branding, images, spatial layout, or writing style.
+  Also use when the user says "my colors look wrong in dark mode", "what font should I use",
+  "is my app accessible enough", "how do I support Dynamic Type", "what contrast ratio do I need",
+  "how do I pick system colors", or "my icons don't match the system style".
+  Cross-references: hig-platforms for platform-specific guidance, hig-patterns for interaction
+  patterns, hig-components-layout for structural components, hig-components-content for display.
+risk: unknown
+source: community
+---
+
+# Apple HIG: Design Foundations
+
+Check for `.claude/apple-design-context.md` before asking questions. Use existing context and only ask for information not already covered.
+
+## Key Principles
+
+1. **Prioritize content over chrome.** Reduce visual clutter. Use system-provided materials and subtle separators rather than heavy borders and backgrounds.
+
+2. **Build in accessibility from the start.** Design for VoiceOver, Dynamic Type, Reduce Motion, Increase Contrast, and Switch Control from day one. Every interactive element needs an accessible label.
+
+3. **Use system colors and materials.** System colors adapt to light/dark mode, increased contrast, and vibrancy. Prefer semantic colors (`label`, `secondaryLabel`, `systemBackground`) over hard-coded values.
+
+4. **Use platform fonts and icons.** SF Pro, SF Compact, SF Mono by default. New York for serif. Follow the type hierarchy at recommended sizes. Use SF Symbols for iconography.
+
+5. **Match platform conventions.** Align look and behavior with system standards. Provide direct, responsive manipulation and clear feedback for every action.
+
+6. **Respect privacy.** Request permissions only when needed, explain why clearly, provide value before asking for data. Design for minimal data collection.
+
+7. **Support internationalization.** Accommodate text expansion, right-to-left scripts, and varying date/number formats. Use Auto Layout for dynamic content sizing.
+
+8. **Use motion purposefully.** Animation should communicate meaning and spatial relationships. Honor Reduce Motion by providing crossfade alternatives.
+
+## Reference Index
+
+| Reference | Topic | Key content |
+|---|---|---|
+| [accessibility.md](references/accessibility.md) | Accessibility | VoiceOver, Dynamic Type, color contrast, motor accessibility, Switch Control, audio descriptions |
+| [app-icons.md](references/app-icons.md) | App Icons | Icon grid, platform-specific sizes, single focal point, no transparency |
+| [branding.md](references/branding.md) | Branding | Integrating brand identity within Apple's design language, subtle branding, custom tints |
+| [color.md](references/color.md) | Color | System colors, Dynamic Colors, semantic colors, custom palettes, contrast ratios |
+| [dark-mode.md](references/dark-mode.md) | Dark Mode | Elevated surfaces, semantic colors, adapted palettes, vibrancy, testing in both modes |
+| [icons.md](references/icons.md) | Icons | Glyph icons, SF Symbols integration, custom icon design, icon weights, optical alignment |
+| [images.md](references/images.md) | Images | Image resolution, @2x/@3x assets, vector assets, image accessibility |
+| [immersive-experiences.md](references/immersive-experiences.md) | Immersive Experiences | AR/VR design, spatial immersion, comfort zones, progressive immersion levels |
+| [inclusion.md](references/inclusion.md) | Inclusion | Diverse representation, non-gendered language, cultural sensitivity, inclusive defaults |
+| [layout.md](references/layout.md) | Layout | Margins, spacing, alignment, safe areas, adaptive layouts, readable content guides |
+| [materials.md](references/materials.md) | Materials | Vibrancy, blur, translucency, system materials, material thickness |
+| [motion.md](references/motion.md) | Motion | Animation curves, transitions, continuity, Reduce Motion support, physics-based motion |
+| [privacy.md](references/privacy.md) | Privacy | Permission requests, usage descriptions, privacy nutrition labels, minimal data collection |
+| [right-to-left.md](references/right-to-left.md) | Right-to-Left | RTL layout mirroring, bidirectional text, icons that flip, exceptions |
+| [sf-symbols.md](references/sf-symbols.md) | SF Symbols | Symbol categories, rendering modes, variable color, custom symbols, weight matching |
+| [spatial-layout.md](references/spatial-layout.md) | Spatial Layout | visionOS window placement, depth, ergonomic zones, Z-axis design |
+| [typography.md](references/typography.md) | Typography | SF Pro, Dynamic Type sizes, text styles, custom fonts, font weight hierarchy, line spacing |
+| [writing.md](references/writing.md) | Writing | UI copy guidelines, tone, capitalization rules, error messages, button labels, conciseness |
+
+## Applying Foundations Together
+
+Consider how principles interact:
+
+1. **Color + Dark Mode + Accessibility** -- Custom palettes must work in both modes while maintaining WCAG contrast ratios. Start with system semantic colors.
+
+2. **Typography + Accessibility + Layout** -- Dynamic Type must scale without breaking layouts. Use text styles and Auto Layout for the full range of type sizes.
+
+3. **Icons + Branding + SF Symbols** -- Custom icons should match SF Symbols weight and optical sizing. Brand elements should integrate without overriding system conventions.
+
+4. **Motion + Accessibility + Feedback** -- Every animation must have a Reduce Motion alternative. Motion should reinforce spatial relationships, not decorate.
+
+5. **Privacy + Writing + Onboarding** -- Permission requests need clear, specific usage descriptions. Time them to when the user will understand the benefit.
+
+## Output Format
+
+1. **Cite the specific HIG foundation** with file and section.
+2. **Note platform differences** for the user's target platforms.
+3. **Provide concrete code patterns** (SwiftUI/UIKit/AppKit).
+4. **Explain accessibility impact** (contrast ratios, Dynamic Type scaling, VoiceOver behavior).
+
+## Questions to Ask
+
+1. Which platforms are you targeting?
+2. Do you have existing brand guidelines?
+3. What accessibility level are you targeting? (WCAG AA, AAA, Apple baseline?)
+4. System colors or custom?
+
+## Related Skills
+
+- **hig-platforms** -- How foundations apply per platform (e.g., type scale differences on watchOS vs macOS)
+- **hig-patterns** -- Interaction patterns where foundations like writing and accessibility are critical
+- **hig-components-layout** -- Structural components implementing layout principles
+- **hig-components-content** -- Content display using color, typography, and images
+
+---
+
+*Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)*
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.