4a5f1234bb
* chore: upgrade maintenance scripts to robust PyYAML parsing - Replaces fragile regex frontmatter parsing with PyYAML/yaml library - Ensures multi-line descriptions and complex characters are handled safely - Normalizes quoting and field ordering across all maintenance scripts - Updates validator to strictly enforce description quality * fix: restore and refine truncated skill descriptions - Recovered 223+ truncated descriptions from git history (6.5.0 regression) - Refined long descriptions into concise, complete sentences (<200 chars) - Added missing descriptions for brainstorming and orchestration skills - Manually fixed imagen skill description - Resolved dangling links in competitor-alternatives skill * chore: sync generated registry files and document fixes - Regenerated skills index with normalized forward-slash paths - Updated README and CATALOG to reflect restored descriptions - Documented restoration and script improvements in CHANGELOG.md * fix: restore missing skill and align metadata for full 955 count - Renamed SKILL.MD to SKILL.md in andruia-skill-smith to ensure indexing - Fixed risk level and missing section in andruia-skill-smith - Synchronized all registry files for final 955 skill count * chore(scripts): add cross-platform runners and hermetic test orchestration * fix(scripts): harden utf-8 output and clone target writeability * fix(skills): add missing date metadata for strict validation * chore(index): sync generated metadata dates * fix(catalog): normalize skill paths to prevent CI drift * chore: sync generated registry files * fix: enforce LF line endings for generated registry files
95 lines
6.2 KiB
Markdown
95 lines
6.2 KiB
Markdown
---
|
|
name: hig-foundations
|
|
description: Apple Human Interface Guidelines design foundations.
|
|
risk: unknown
|
|
source: community
|
|
date_added: '2026-02-27'
|
|
---
|
|
|
|
# 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.
|