apple-glass

Files (2)

• RECIPES.md
• SKILL.md

SKILL.md (first lines)

# Apple Glass — Mobile-First Glass & Refraction Engine

The single source of truth for all **"frosted glass"**, **"apple glass"**, and **"liquid glass"** implementations across the command center and projects. 

Every recipe here is engineered **mobile-first**: locked 60/120fps scrolling on iOS Safari and Android Chrome, zero thermal throttling, zero WebGL context exhaustion, and full accessibility support.

---

## 1. The Mobile-First Invariant

Desktop web demos frequently cheat by taking canvas screenshots of the page (`html2canvas` in `dashersw/liquid-glass-js`) or spinning up full-screen 3D WebGL canvases with multi-pass Frame Buffer Objects (`MeshTransmissionMaterial` in Three.js).

On mobile devices, these desktop shortcuts fail catastrophically:
* **The Static Snapshot Trap:** `html2canvas` captures the page once at load time. When a mobile user scrolls, the glass displays a frozen, misplaced snapshot of the top of the page. Re-running `html2canvas` on scroll freezes the mobile CPU for 200–1,000ms per frame.
* **WebGL Context Limits:** Mobile Safari caps concurrent WebGL contexts at 8–16 system-wide. Adding separate WebGL canvases for navigation pills and cards quickly crashes the browser with `CONTEXT_LOST_WEBGL`.
* **Thermal Throttling & Battery Drain:** FBO multi-sampling (10 samples per pixel on a 3x Retina display) exhausts mobile GPUs within seconds.
* **Non-Refractive DOM:** 3D WebGL materials cannot refract HTML text, buttons, or inputs underneath them — only 3D geometry inside their own canvas.

**The House Rule:** 
1. Use **Tier 1 (CSS/Tailwind Compositor Glass)** for 95% of UI: cards, sheets, headers, navigation bars, and modals.
2. Use **Tier 2 (SDF Filter Live DOM Refraction via `@samasante/liquid-glass`)** only for dedicated refractive controls: Dynamic Island pills, floating action buttons, and slider thumbs.
3. Never use `html2canvas`, SVG foreignObject screenshotting, or 3D WebGL canvases for 2D UI elements.

---

## 2. Decision Matrix: Which Glass to Use

| Use Case | Recommended Engine | Platform | Performance |
|---|---|---|---|
| **Cards, Modals, Navigation Bars, Tab Bars, Dropdowns** | **Tier 1: Apple HIG Frosted Glass** | Web / Next.js / Tailwind | Native Compositor (120fps, 0 JS overhead) |
| **Interactive Lenses, Floating Pills, Dynamic Island, Sliders** | **Tier 2: Apple Liquid Glass (`@samasante/liquid-glass`)** | Web / Next.js / React | SVG SDF filter over live DOM (<5KB, 0 deps) |
| **Native iOS / iPadOS Apps (React Native)** | **Tier 3: `@callstack/liquid-glass`** | React Native / Expo | Native UIKit / SwiftUI bridge (120Hz ProMotion) |
| **Native iOS Apps (Swift / SwiftUI)** | **Tier 3: `.glassEffect()`** | iOS 26+ Native Swift | Apple Native Framework (`GlassEffectContainer`) |
| **True 3D Spatial Geometry / GLTF Models** | **[`visual-fx-3d`](../visual-fx-3d/SKILL.md)** | WebGL / R3F / Drei | Dedicated 3D Canvas only (not for DOM UI) |

---

## 3. Tier 1: Apple HIG Frosted Glass (CSS & Tailwind)

This is Apple's production standard for the iOS Control Center, Safari tab bars, Lock Screen widgets, and modal sheets. It runs entirely on the mobile GPU's hardware compositor without JavaScript overhead.

### The Apple Glass Formula
Authentic Apple frosted glass requires three coordinated optical layers:
1. **`backdrop-saturate-180`**: Apple's hallmark vibrancy. Boosts color saturation behind the glass by 180% to prevent the backdrop from looking like dull milky plastic.
2. **`backdrop-blur-xl` (or `backdrop-blur-2xl`)**: Heavy Gaussian blur that diffuses background shapes into pure ambient illumination.
3. **Sub-Pixel Specular Border (`border border-white/20`)**: A 1px translucent highlight simulating the physical cut edge of beveled glass catching ambient room light.
4. **Top Rim Sheen Gradient**: A 1px horizontal gradient across the top rim simulating overhead light reflection.

### Production Recipe: Floating Mobile Tab Bar / Nav Card

```tsx
export function AppleFrostedCard({ 
  children, 
  className = '' 
}: { 
  children: React.ReactNode; 
  className?: string; 
}) {
  return (
    <div className={`
      relative overflow-hidden rounded-3xl
      /* Translucent Surface: Dark Mode vs Light Mode */
      bg-neutral-900/65 dark:bg-neutral-900/65 bg-white/75
      /* The Apple Formula */
      backdrop-blur-xl backdrop-saturate-180
      /* Sub-Pixel Specular Rim Border */
      border border-white/20 dark:border-white/10
      /* Subtle Ambient Shadow */
      shadow-[0_8px_32px_0_rgba(0,0,0,0.18)]
      /* Prevent iOS Safari composite bleed */
      transform-gpu isolation-isolate
      ${className}
    `}>
      {/* Top Specular Rim Reflection */}
      <div 
        aria-hidden="true"
        className="pointer-events-none absolute inset-x-0 top-0 h-px bg-gradient-to-r from-transparent via-white/30 dark:via-white/20 to-transparent" 
      />
      
      {/* Interactive Content */}
      <div className="relative z-10">
        {children}
      </div>
    </div>
  );
}
```

### Mobile Touch Active States
When building touchable glass controls (chips, buttons, segmented controls), combine with Emil Kowalski spring motion and an inner glow:

```tsx
<button className="
  px-4 py-2.5 rounded-full text-sm font-medium text-white
  bg-white/10 hover:bg-white/15 active:bg-white/25
  backdrop-blur-lg backdrop-saturate-180
  border border-white/20 active:scale-95
  transition-all duration-150 ease-out
">
  Cockpit View
</button>
```

### Accessibility Fallback
Always respect user preferences for reduced transparency (`prefers-reduced-transparency`):
```css
@media (prefers-reduced-transparency: reduce) {
  .apple-glass {
    backdrop-filter: none !important;
    background-color: rgb(23 23 23 / 0.95) !important;
  }
}
```
In Tailwind: `contrast-more:bg-neutral-950/95 contrast-more:backdrop-blur-none`.

---

## 4. Tier 2: Apple Liquid Glass (Refractive Lens via `@samasante/liquid-glass`)

From sudomadhatter/design-engineer-skills, MIT.

More from sudomadhatter/design-engineer-skills