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

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

Stage 2: Global Shell & Navigation — COMPLETED

• Sidebar refinement: accent-colored hover states, border-left active indicator, collapse animation
• Separator between nav items and utility items (Settings, Logout)
• Global transitions and loading states (skeleton screens)
• Custom scrollbar applied everywhere (accent-tinted on hover)

Stage 3: Calendar Redesign & Improvements — COMPLETED

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

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

Projects — COMPLETED

• Refined filter bar components
• Improved card designs (progress bars, status badges)
• Better empty states with contextual illustrations or suggestions
• Consistent hover/click affordances

Todos — COMPLETED

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

Reminders — COMPLETED

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

Reminder Alerts — COMPLETED

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