PixelPilot uiux-temporal-ui.instructions.md

Temporal UI — Time-Aware Interfaces

Time matters. A dashboard at 2am should feel different than at 2pm. This file covers time-of-day theming, deadline urgency, personalized greetings, and building interfaces that respect temporal context.

---

CRITICAL RULES

1. User timezone — Always use client-side time, not server time.
2. Privacy — Don't log/track user's local time without consent.
3. Override option — Let users disable time-based features.
4. Graceful transitions — Theme changes should be smooth, not jarring.
5. Accessibility — Never rely solely on color for urgency.

---

TIME-OF-DAY THEME

Automatic theme based on local time:

// temporalTheme.ts
type TimeOfDay = 'night' | 'morning' | 'afternoon' | 'evening';

interface TimeConfig {
  night: { start: number; end: number };      // 22:00 - 06:00
  morning: { start: number; end: number };    // 06:00 - 12:00
  afternoon: { start: number; end: number };  // 12:00 - 18:00
  evening: { start: number; end: number };    // 18:00 - 22:00
}

const defaultConfig: TimeConfig = {
  night: { start: 22, end: 6 },
  morning: { start: 6, end: 12 },
  afternoon: { start: 12, end: 18 },
  evening: { start: 18, end: 22 },
};

export function getTimeOfDay(config = defaultConfig): TimeOfDay {
  const hour = new Date().getHours();
  
  if (hour >= config.night.start || hour < config.night.end) return 'night';
  if (hour >= config.morning.start && hour < config.morning.end) return 'morning';
  if (hour >= config.afternoon.start && hour < config.afternoon.end) return 'afternoon';
  return 'evening';
}

export function applyTemporalTheme(): void {
  // Respect manual override
  if (localStorage.getItem('theme-manual') === 'true') return;
  
  const timeOfDay = getTimeOfDay();
  const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  
  // Combine time + system preference
  let theme: string;
  if (timeOfDay === 'night') {
    theme = 'dark';
  } else if (timeOfDay === 'evening' && systemPrefersDark) {
    theme = 'dark';
  } else if (timeOfDay === 'morning') {
    theme = 'light-warm'; // Slightly warmer morning light
  } else {
    theme = 'light';
  }
  
  document.documentElement.setAttribute('data-theme', theme);
  document.documentElement.setAttribute('data-time-of-day', timeOfDay);
}

// Update every 15 minutes
export function initTemporalTheme(): () => void {
  applyTemporalTheme();
  const interval = setInterval(applyTemporalTheme, 15 * 60 * 1000);
  return () => clearInterval(interval);
}