Skip to content

PROJECT_SPEC.md

Latest commit

 

History

History
128 lines (110 loc) · 5.91 KB

PROJECT_SPEC.md

File metadata and controls

128 lines (110 loc) · 5.91 KB
Raw

Sky Wallpaper — Coloring Book Dynamic Sky for macOS

Overview

A single-page HTML/JS application that renders an animated, weather-reactive sky inspired by the color palette of Chance the Rapper's "Coloring Book" album cover. The sky is displayed as a macOS desktop wallpaper via Plash (free, open-source app that renders any webpage as your desktop background).

Hosting

  • Deploy to GitHub Pages or Vercel (single index.html)
  • Plash points at the deployed URL
  • No build step required — everything lives in one file

Tech Stack

  • Three.js (via CDN: https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js)
  • Open-Meteo Weather API (free, no API key, CORS-friendly)
  • Vanilla JS — no framework, no build tools
  • Single index.html file with all CSS/JS inline

Color Palette (from Coloring Book cover)

Reference the uploaded album cover image. Key colors:

  • Sky gradient: warm coral/salmon pink (#E8655A → #D94E63) blending into soft peach (#F4A683)
  • Cloud highlights: warm white/cream with pink tinge
  • Cloud shadows: muted purple/mauve (#6B3A5D → #8B5E7D)
  • Stars/sparkles: soft warm white (#FFF5E6) with subtle glow
  • Night shift: deeper purples (#2D1B3D), indigo (#1A1040), maintaining warmth
  • Blue-tinted elements: cool blue (#1E3A5F → #2B5C8A) — used sparingly

These should shift based on time of day and weather conditions.

Animation Style

  • Subtle and dreamy — slow, meditative, almost hypnotic
  • Slow-drifting cloud layers at different depths (parallax)
  • Gentle twinkling stars/sparkles
  • Soft gradient transitions, never harsh
  • Target: 30-60fps, low CPU usage (this runs 24/7 as a wallpaper)

Weather-Reactive Behaviors

Fetch weather data every 10-15 minutes from Open-Meteo for Hillside, NJ (lat: 40.6954, lon: -74.2285).

Cloud density/darkness reacting to cloud cover

  • Open-Meteo field: cloud_cover (0-100%)
  • Clear (0-20%): sparse, wispy clouds, lots of sky visible
  • Partly cloudy (20-60%): moderate cloud coverage
  • Overcast (60-100%): dense, darker clouds filling the sky

Rain/snow particles when precipitating

  • Open-Meteo fields: precipitation, rain, snowfall, weather_code
  • Rain: streak particles falling at angle, subtle splash effect
  • Snow: slower, drifting particle system, white/soft blue
  • Intensity scales with precipitation amount

Star visibility based on time of day

  • Open-Meteo fields: is_day or calculate from sunrise/sunset times
  • Daytime: no stars, bright sky
  • Dusk/dawn (within 1hr of sunrise/sunset): stars begin to appear/fade
  • Night: full starfield with twinkling animation

Color palette shifting

  • Sunrise/sunset: warmest palette — vivid corals, pinks, oranges (most "Coloring Book")
  • Daytime clear: lighter, brighter version of the palette
  • Daytime overcast: desaturated, slightly gray-shifted
  • Night clear: deep purples and indigo, stars prominent
  • Night overcast: darker, moodier, minimal stars
  • Use smooth lerp transitions between palettes (never snap)

Weather Code Reference (Open-Meteo WMO codes)

  • 0: Clear sky
  • 1-3: Mainly clear, partly cloudy, overcast
  • 45, 48: Fog
  • 51-55: Drizzle (light/moderate/dense)
  • 61-65: Rain (slight/moderate/heavy)
  • 71-75: Snow fall (slight/moderate/heavy)
  • 80-82: Rain showers
  • 85-86: Snow showers
  • 95-99: Thunderstorm

Open-Meteo API Call

https://api.open-meteo.com/v1/forecast?latitude=40.6954&longitude=-74.2285&current=temperature_2m,relative_humidity_2m,weather_code,cloud_cover,precipitation,rain,snowfall,is_day,wind_speed_10m&daily=sunrise,sunset&timezone=America/New_York

Performance Constraints

  • This runs 24/7 behind desktop icons via Plash (WKWebView)
  • Target: <5% CPU on Apple Silicon (M4 Pro)
  • Use requestAnimationFrame with frame skipping if needed
  • Consider reducing particle counts / draw calls
  • Plash supports transparent background — could layer over system wallpaper
  • Weather fetch interval: every 15 minutes (Open-Meteo rate limit: 10,000 calls/day)

Architecture Suggestions

index.html
├── <style> — fullscreen canvas, no scroll, no margin
├── <canvas> or Three.js renderer (fullscreen)
├── <script> Three.js via CDN
└── <script> Main application
    ├── WeatherService — fetches + caches Open-Meteo data
    ├── TimeService — tracks time of day, sunrise/sunset
    ├── SkyRenderer — gradient background, color palette blending
    ├── CloudSystem — procedural cloud layers with parallax drift
    ├── StarField — twinkling star particles (night only)
    ├── PrecipitationSystem — rain/snow particles (weather-driven)
    └── AnimationLoop — requestAnimationFrame orchestrator

Key References

Development Workflow

  1. Build and test in browser (open index.html or local server)
  2. Iterate on visuals — get the Coloring Book palette right first
  3. Add weather integration
  4. Deploy to GitHub Pages / Vercel
  5. Install Plash, point at URL, enjoy

Future Ideas

  • Geolocation API so it works anywhere, not just Hillside
  • Music reactivity (stretch goal)
  • Subtle lightning flashes during thunderstorms
  • Moon phase rendering
  • Fog/mist overlay for fog weather codes