---
name: apple-hig-design
description: NarmaForge Cupertino & Swift: clarity, deference, depth, optical typography, materials, physics, and Swift architecture.
---

# NarmaForge Cupertino Foundation & Universal Multi-Stack Engine

An exhaustive, language-agnostic extraction of Apple Human Interface Guidelines and Swift/SwiftUI engineering paradigms for Web, Flutter, React Native, Kotlin Multiplatform, and SwiftUI applications.

## 1. Architectural Pillars
- **Clarity**: Content legibility across all scales, precision iconography, and high-contrast typography.
- **Deference**: Content is the hero. Interface chrome, fluid transitions, and glass materials recede.
- **Depth**: Realistic visual layers, z-index hierarchy, background dimming, and contextual sheets.

## 2. Exhaustive Engineering & Design Modules
Load specific references based on active project requirements:

1. [**Core Principles & Materials**](references/core-principles-and-materials.md):
   The 3 interaction pillars, continuous curvature squircle equations, safe area insets, 44x44pt touch target ergonomics, and 4-tier vibrancy backdrop blurs.
2. [**Typography & Color System**](references/typography-and-colors.md):
   SF Pro Text vs. SF Pro Display optical size boundaries, mathematical tracking tables, tabular figures, adaptive system colors, and label/surface tiers.
3. [**Motion Physics & Haptics**](references/motion-physics-and-haptics.md):
   Damped harmonic oscillator equations, interactive spring curves, modal sheet detents (medium/large), swipe-to-dismiss velocity, and sensory haptic patterns.
4. [**Components & Controls Catalog**](references/components-and-controls.md):
   System bars (Navigation, Tab, Search), button styles (Filled, Tinted, Gray, Plain), segmented pickers, toggles, sliders, steppers, and inset grouped lists.
5. [**Patterns & Navigation Models**](references/patterns-and-navigation.md):
   Hierarchical stacks, split views, tokenized search, Dynamic Island states (Compact, Minimal, Expanded), Live Activities, and biometric privacy.
6. [**Spatial Computing & Platform Matrix**](references/spatial-vision-and-platforms.md):
   visionOS spatial computing (Windows, Volumes, Gaze & Pinch, Ornaments), macOS menu bars/sidebars, iPadOS multitasking, watchOS rotary, and tvOS Focus Engine.
7. [**Input Modalities & Accessibility**](references/input-modalities-and-accessibility.md):
   Touch gestures, Apple Pencil (hover, squeeze, tilt), hardware keyboard shortcuts `⌘`, visionOS eye-gaze targeting (60pt rule), VoiceOver, and Dynamic Type.
8. [**Universal Token Engine**](references/universal-token-engine.md):
   Language-agnostic token definitions in W3C JSON, Tailwind CSS config, Flutter CupertinoTheme, React Native StyleSheet, and Jetpack Compose tokens.
9. [**Multi-Stack Code Recipes**](references/multi-stack-code-recipes.md):
   Side-by-side production code recipes for Cupertino Buttons and Inset Grouped Lists across React, Flutter, React Native, SwiftUI, and Jetpack Compose.
10. [**Swift 6 Language Architecture**](references/swift-language-architecture.md):
    Actor isolation, `@MainActor` thread safety, Sendable checks, structured tasks (`async let`, `TaskGroup`), the `@Observable` framework, and macros.
11. [**SwiftUI Declarative Architecture**](references/swiftui-declarative-patterns.md):
    View tree composition, state wrappers (`@State`, `@Binding`, `@Bindable`, `@Environment`), custom `Layout` protocol, `ViewThatFits`, and `NavigationStack`.
12. [**Web Translation Engine**](references/web-translation-engine.md):
    Direct mapping from SwiftUI primitives/modifiers to semantic HTML5, CSS custom properties (`--narma-cupertino-*`), CSS Grid/Flexbox, and accessible ARIA.
13. [**Materials & Motion Reference Index**](references/materials-and-motion.md):
    Cross-reference index redirecting to Core Principles & Materials and Motion Physics & Haptics.

## 3. Quick Universal Implementation Checklist
- Maintain minimum **$\ge 44\times 44$pt** touch targets on all interactive controls.
- Enforce optical text tracking: looser letter spacing under 20pt, tighter above 20pt.
- Use continuous squircle corner radii (`border-radius` with continuous curvature).
- Apply physical spring curves (`cubic-bezier(0.25, 1, 0.5, 1)`) rather than linear or ease-in-out easing.
- Keep components responsive and accessible across any programming language.