UMBRA/.claude/projects/ui_refresh.md

# UMBRA UI Refresh — Planning Document

## Current UI Audit (2026-02-20)

### Global Observations
- **Theme:** Dark background (~#0a0a0a), dark card surfaces (~#1a1a2e), blue/cyan accent
- **Sidebar:** Fixed left ~200px, solid blue highlight on active item, Lucide icons + labels, collapse chevron
- **Typography:** System sans-serif, white headings, muted gray subtext — functional but lacks personality
- **Cards:** Rounded borders with subtle gray stroke, no shadows, no hover effects, no transitions
- **Layout:** Full-width content area with no max-width constraint — cards stretch awkwardly on wide displays
- **Action buttons:** Consistent "+ Add X" blue filled buttons top-right on every page — good pattern
- **Empty states:** Centered icon + message — functional but lifeless
- **Scrollbars:** Default browser scrollbars — clash with dark theme

### Page-by-Page Notes

#### Login
- Centered dark card, lock icon, PIN input, blue "Unlock" button
- Clean and minimal — works well structurally
- Missing UMBRA branding/identity — feels like a generic auth screen
- No ambient atmosphere (no gradients, no glow, no texture)

#### Dashboard
- 4 stat cards across top (Total Projects, In Progress, People, Locations) with colored Lucide icons
- "Upcoming (7 days)" section — flat list of events with "Event" badge right-aligned
- Bottom row: "Upcoming Todos" + "Today's Events" side by side
- **Issues:**
  - Stat cards are flat rectangles with label/number/icon — no visual weight or hierarchy
  - Icon colors (purple, purple, green, orange) feel arbitrary — no semantic meaning
  - Upcoming list wastes horizontal space — event name far left, badge far right, nothing in between
  - Bottom widgets have massive empty space when few/no items
  - No week summary or schedule preview — missed opportunity for at-a-glance context
  - "Welcome back. Here's your overview." is generic placeholder text
  - No time-of-day awareness or contextual greeting

#### Todos
- Search bar + "All Priorities" dropdown + category filter + "Show completed" checkbox
- All controls on single line — functional but cramped and visually flat
- Empty state: centered checkbox icon + message
- **Issues:** Filter controls are unstyled native elements mixed with custom — inconsistent

#### Calendar (Month)
- FullCalendar month view with colored event dots/pills
- Color coding: blue (default), purple, green (multi-day), orange, yellow
- **Issues:**
  - Prev/next navigation arrows are tiny unstyled squares (~16px) — nearly invisible
  - "today" button is plain text with no visual emphasis
  - Event text truncates on small cells with no tooltip or expand affordance
  - Multi-day events (green/orange bars) visually dominate and obscure day cells
  - No visual distinction for today's date in month grid

#### Calendar (Week)
- Time grid with events as colored blocks — time + title visible
- Today column has yellowish-brown tint overlay
- **Issues:**
  - The "today" tint is murky (#8B8000-ish overlay) — looks dirty rather than highlighted
  - Past-time columns also have this tint, making it confusing
  - No current-time indicator line

#### Calendar (Day)
- Full-day column with same murky brown-yellow background
- **Issues:** When empty, entire content area is just a brown column — unappealing
  - No visual distinction between past hours and future hours

#### Reminders
- Tab bar: Active / Dismissed / All — clean blue active state
- Empty state similar to Todos
- Very sparse — large empty space below tabs

#### Projects
- 3-column card grid
- Each card: ALL-CAPS name, status badge pill, "Progress" label with thin bar, task count, calendar icon + due date
- **Issues:**
  - ALL-CAPS names are aggressive and hard to scan
  - Status badges ("not started" / "in progress") are small outlined pills — low contrast
  - Progress bars are extremely thin (~2px) and low-contrast against dark surface
  - "Progress" label + "0/3 tasks" on same line wastes vertical space
  - Cards have uneven internal spacing — description shows on some, not others
  - No hover state or click affordance — cards don't feel interactive

#### People
- 3-column card grid
- Each card: name, category badge (Friends = blue, Work = gray), birthday, edit/delete icons top-right
- **Issues:**
  - Cards feel sparse — just 3 lines of info in a large rectangle
  - No avatar placeholder — missed opportunity for visual anchoring
  - Edit (pencil) and delete (trash) icons are small and far from the name
  - Category badge colors don't match Locations page (Work = gray here, purple there)

#### Locations
- 3-column card grid with location pin icon beside name
- Category badges: home = blue, work = purple
- Address shown as subtitle
- **Issues:** Badge color system inconsistent with People page

#### Settings
- Three stacked sections: Appearance, Dashboard, Security
- Left-aligned at ~50% width, entire right half is empty
- Accent color picker: 5 colored circles (cyan, blue, purple, orange, green)
- **Issues:**
  - Massive dead space on right — feels incomplete
  - Color circles have no labels or tooltips
  - Sections could use visual separation beyond just spacing

---

## Design Critique (Frontend Design Review)

### 1. Surface & Depth — "Everything lives on the same plane"
The biggest visual issue is that every element — cards, sidebar, content area, stat widgets — exists at the same depth. There are no shadows, no layering, no elevation changes. Modern dark UIs use subtle elevation to create hierarchy:
- Cards should float slightly above the background with soft box-shadows (`0 1px 3px rgba(0,0,0,0.3)`)
- The sidebar should feel like a separate layer with a subtle border or shadow on its right edge
- Hover states should lift cards slightly (`translateY(-1px)` + shadow increase)
- Active/selected states should have a gentle inner glow or border luminance shift

### 2. Typography — "Functional but forgettable"
The current type system is plain system sans-serif with two weights (bold headings, normal body). For a personal life manager named "UMBRA," typography should reinforce brand identity:
- Consider a distinctive heading font (geometric sans like Outfit, Sora, or General Sans)
- Body text needs slightly more line-height for readability on dark backgrounds (1.6 minimum)
- The ALL-CAPS project names are too aggressive — use sentence case with semibold weight instead
- Stat card numbers should be larger and use tabular figures for alignment
- Muted text (#6b7280-range) is too low-contrast on dark backgrounds — bump to #9ca3af minimum

### 3. Color System — "Arbitrary accents without semantic meaning"
Colors are applied without a clear system:
- Stat card icons use purple/purple/green/orange — why purple twice? No semantic connection
- Category badges are inconsistent: Work is gray on People, purple on Locations
- The calendar today overlay (#8B8000-ish) clashes with the cool-toned theme
- **Recommendation:** Establish a semantic color palette:
  - Accent (cyan/blue): interactive elements, active states, links
  - Success (emerald): completed, on-track
  - Warning (amber): upcoming, due soon
  - Danger (rose): overdue, delete
  - Neutral (slate): secondary text, borders, disabled
  - Category colors should be consistent app-wide (same color for "Work" everywhere)

### 4. Spacing & Density — "Too much air, not enough content"
- Dashboard stat cards have generous internal padding but minimal content — lots of dead space
- The Upcoming list is a single-column spanning the full width with text far-left and badge far-right
- Settings page uses only half the viewport width
- Cards on People/Locations show 3 lines of info in ~150px tall containers
- **Recommendation:** Use a tighter grid system. Dashboard should use a 2-column or asymmetric layout below stats. Cards should breathe but not float in empty space. Consider max-width containers (1200-1400px).

### 5. Interactivity — "Static pages, not a living app"
Zero motion, zero feedback:
- No hover states on any cards or interactive elements
- No transitions on page changes
- No loading states or skeleton screens
- No micro-interactions (checkbox toggle, card expand, badge pulse)
- Scrollbars are default browser chrome — jarring in dark theme
- **Recommendation:** Add CSS transitions on all interactive elements (150-200ms ease). Custom scrollbar styling with `scrollbar-color` and `::-webkit-scrollbar`. Subtle scale/shadow on card hover.

### 6. Dashboard Specific — "A bulletin board, not a command center"
The dashboard is the first thing you see and it should feel alive:
- Missing: week-at-a-glance schedule/timeline
- Missing: contextual greeting (time of day + name)
- Missing: quick actions or shortcuts
- Stat cards don't link context — "5 Projects" but which ones matter right now?
- Bottom widgets (Upcoming Todos / Today's Events) are equal-width but Today's Events is more urgent
- **Recommendation:** Redesign dashboard as a "morning briefing" — today's schedule, this week's priorities, active project progress, quick-add shortcuts

### 7. Component Quality — "Default HTML with Tailwind"
Several components feel like unstyled defaults:
- Calendar nav arrows are default FullCalendar squares — need custom styled buttons
- Filter dropdowns on Todos look like native `<select>` elements
- Progress bars are 2px thin lines — should be thicker (6-8px) with rounded ends and gradient fills
- Badge pills lack padding consistency and weight

---

## Implementation Stages

### Stage 1: Dashboard Overhaul — COMPLETED
- [x] Redesign dashboard layout: greeting, week summary, stat cards, upcoming events, today's schedule
- [x] Establish new card component with shadows, hover states, transitions
- [x] Add custom scrollbar styling globally
- [x] Set up CSS custom properties for the refined color system
- [x] **Deliverable:** Polished dashboard + `stylesheet.md` capturing the new design language
- [x] Typography: Sora headings + DM Sans body
- [x] Contextual greeting (time-of-day aware)
- [x] Week-at-a-glance timeline with today highlight + event dots
- [x] Stat cards with gradient backgrounds, semantic icon colors, tabular numbers
- [x] Upcoming widget with type badges + priority pills
- [x] Today's Events + Upcoming Todos + Active Reminders sidebar widgets
- [x] Weather widget with location search
- [x] Staggered fade-in/slide-up animations
- [x] Smart nudge bar (contextual tips below week timeline)

### Stage 2: Global Shell & Navigation — COMPLETED
- [x] Sidebar refinement: accent-colored hover states, border-left active indicator, collapse animation
- [x] Separator between nav items and utility items (Settings, Logout)
- [x] Global transitions and loading states (skeleton screens)
- [x] Custom scrollbar applied everywhere (accent-tinted on hover)

### Stage 3: Calendar Redesign & Improvements — COMPLETED
- [x] Multi-calendar backend: user-created calendars with color, virtual birthday calendar from People
- [x] Calendar sidebar with collapsible calendar list, visibility toggles, color indicators
- [x] Custom-styled toolbar: prev/next/today buttons, segmented Month/Week/Day view switcher
- [x] Calendar header alignment with global UMBRA header (h-16), no border wrapper
- [x] ResizeObserver for sidebar collapse → calendar auto-resizes
- [x] Sheet component (`sheet.tsx`): slide-in panel replacing Dialog for all forms
- [x] All 4 forms migrated to Sheet: EventForm, TodoForm, ReminderForm, LocationForm
- [x] Form layout improvements: 2-column grids for related fields, wider textareas
- [x] All-day event fixes: slim CSS bars, exclusive end-date offset (display ↔ save)
- [x] Materialized recurring events backend: migration, model, service, router
- [x] Recurrence UI: structured picker (every N days, weekly, monthly nth weekday, monthly date)
- [x] Edit/delete scope dialog for recurring events ("This event only" / "This and all future")
- [x] Drag-drop/resize guards for recurring events (reverts with info toast)
- [x] LocationPicker component with OSM Nominatim integration + local DB search
- [x] LocationPicker integrated into EventForm and LocationForm
- [x] First day of week setting (Sunday/Monday) in Settings with calendar sync
- [x] FullCalendar reactivity fix: key prop for firstDay remount
- [x] Dashboard/upcoming queries: parent template exclusion filter (no duplicates)
- [x] DayBriefing: null guards on end_datetime, reminders in night briefing, pre-5AM today awareness
- [x] Recurrence crash fixes: null field stripping, _rule_int helper, first-occurrence generation
- [x] Event templates: removed unused duration_minutes field, added Alembic migration
- [x] TemplateForm converted from Dialog to Sheet side panel (matches EventForm)
- [x] EventForm auto-prefills start=now, end=now+1h for new events (no calendar selection needed)
- [x] EventForm distinguishes template-based creation ("Create Event from X Template") from editing
- [x] LocationPicker mount guard: prevents auto-open dropdown on pre-filled forms

### Stage 4: CRUD Pages (Todos, Reminders, Projects)

#### Projects — COMPLETED
- [x] Refined filter bar components
- [x] Improved card designs (progress bars, status badges)
- [x] Better empty states with contextual illustrations or suggestions
- [x] Consistent hover/click affordances

#### Todos — COMPLETED
- [x] Compact h-16 header with segmented priority filter, search, category dropdown, show-completed toggle
- [x] Summary stat cards (Open, Completed, Overdue)
- [x] Single-line compact row design (list-view convention: no card borders, hover:bg-card-elevated)
- [x] Priority pills, category badges, recurrence badges inline
- [x] Overdue/today date coloring, due time display
- [x] Grouped sections (Overdue → Today → Upcoming → No Due Date → Completed)
- [x] Empty state with "Add Todo" action button
- [x] Recurrence logic: auto-reset scheduling (daily/weekly/monthly), reset info display
- [x] Optional due time field, fixed date not being truly optional

#### Reminders — COMPLETED
- [x] Compact h-16 header with segmented status filter (Active/Dismissed/All), search input
- [x] Summary stat cards (Active, Overdue, Dismissed) with semantic icon colors
- [x] Single-line compact row design (ReminderItem) matching TodoItem pattern
- [x] Grouped sections (Overdue → Today → Upcoming → No Date → Dismissed)
- [x] Recurrence badge inline, date coloring (red overdue, yellow today, muted future)
- [x] Dismiss button, edit button, 4-second confirm delete with "Sure?" label
- [x] Optimistic delete with rollback
- [x] Empty state with "Add Reminder" action button
- [x] ReminderForm uses single datetime-local input (matches EventForm) with recurrence alongside

#### Reminder Alerts — COMPLETED
- [x] Backend: `snoozed_until` column + Alembic migration 017 with composite index
- [x] Backend: `GET /api/reminders/due` endpoint (overdue, non-dismissed, non-recurring, snooze-aware)
- [x] Backend: `PATCH /api/reminders/{id}/snooze` with `Literal[5, 10, 15]` validation + state guards
- [x] Backend: Snooze/due endpoints accept `client_now` from frontend (fixes Docker UTC vs local time)
- [x] Backend: Dismiss clears `snoozed_until`; updating `remind_at` reactivates dismissed reminders
- [x] Frontend: `AlertsProvider` context in AppLayout — single polling instance, no duplicate toasts
- [x] Frontend: `useAlerts` hook polls `/reminders/due` every 30s with client_now
- [x] Frontend: Sonner custom toasts on non-dashboard pages (max 3 + overflow summary, `duration: Infinity`)
- [x] Frontend: `AlertBanner` on dashboard below stats row (orange left accent, compact rows)
- [x] Frontend: `SnoozeDropdown` component — clock icon + "Snooze" label, opens dropdown with 5/10/15 min options
- [x] Frontend: Toast/banner dismiss button with X icon + "Dismiss" label
- [x] Frontend: Route-aware display — toasts dismissed on dashboard entry, fired on exit
- [x] Frontend: Dashboard Active Reminders card filters out items already in AlertBanner
- [x] Frontend: Shared `getRelativeTime` + `toLocalDatetime` utilities in `lib/date-utils.ts`
- [x] Accessibility: aria-labels on all snooze/dismiss buttons

### Stage 5: Entity Pages (People, Locations)
- Avatar placeholders for People cards
- Consistent category badge colors app-wide
- Denser card layout with more visible info

### Stage 6: Settings & Login
- Settings: full-width responsive layout, labeled color picker, section cards
- Login: UMBRA branding, ambient background effect

### Stage 7: Final Polish
- Cross-page consistency audit
- Animation timing review
- Accessibility pass (contrast ratios, focus states)
- Performance review (no layout shifts, smooth transitions)

---

## User Requirements
- Maintain dark minimalist theme with accent colors
- More modern, softer, cleaner aesthetic
- Less dead space in UI elements
- Themed scrollbars matching the dark UI
- Dashboard: include a summary of the current week
- Incremental implementation — dashboard first, then style guide, then remaining pages

## Refresh Scope

**Current status:** Stages 1-4 complete, plus Reminder Alerts feature. Next up: Stage 5 Entity Pages (People, Locations).