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

### Stage 4: CRUD Pages (Todos, Reminders, Projects)
- Refined filter bar components
- Improved card designs (Projects: progress bars, status badges)
- Better empty states with contextual illustrations or suggestions
- Consistent hover/click affordances

### 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
_~~Dashboard first (Stage 1) → style-guide.md~~ → Stage 3 (Calendar) next → remaining stages in order._

**Current status:** Stages 1-3 complete. Stylesheet established. Calendar redesign with recurrence, multi-calendar, sheet forms, and LocationPicker done. Next up: Stage 4 (CRUD Pages).