mitlist/planfrontend.md
2025-06-30 08:16:25 +02:00

14 KiB

Household Management App: Vue + Headless UI Refactor Specification

Executive Summary

This document outlines a comprehensive refactor strategy to transform the current household management app into a frictionless, conflict-reducing platform using Vue 3 with Composition API and headless UI libraries. The focus is on achieving sub-5-second interactions, zero-ambiguity states, and maximum adoption through radical simplification.

Core Design Philosophy

The 3-2-1 Rule

  • 3 seconds: Maximum time from app open to actionable information
  • 2 taps: Maximum interaction depth for common actions
  • 1 source of truth: Every piece of information has exactly one authoritative display

Friction Elimination Principles

  1. Cognitive Load Minimization: Default to the most common choice
  2. Progressive Disclosure: Advanced features emerge only when needed
  3. Optimistic UI: Show results immediately, sync in background
  4. Contextual Actions: Surface relevant actions based on current state

Technical Architecture Overview

Vue 3 + Headless UI Stack

  • Vue 3.4+ with Composition API and <script setup>
  • Headless UI Vue for accessible, unstyled components
  • Tailwind CSS 3.4+ with custom design tokens
  • VueUse for composables and utilities
  • Pinia for state management with persistence
  • Vue Router 4 with lazy loading
  • Vite for build tooling and HMR

State Management Strategy

  • Global Store Pattern: Centralized household data with reactive updates
  • Optimistic Updates: UI responds immediately, queues API calls
  • Offline-First: Local persistence with background sync
  • Real-time Sync: WebSocket connections for live updates

Information Architecture Redesign

Current State Analysis

Most household apps fail because they:

  • Require too many decisions upfront
  • Hide critical information behind navigation
  • Create anxiety through overdue notifications
  • Generate conflicts through unclear responsibilities

New Information Hierarchy

Dashboard (Home) - Single source of truth
├── Personal Status (Above fold)
│   ├── My Next Action (1 item max)
│   ├── My Financial Status (Net balance)
│   └── Quick Win Suggestion
├── Universal Actions (FAB)
│   ├── Add Expense (80% of usage)
│   ├── Complete Chore (15% of usage)
│   └── Add to List (5% of usage)
└── Activity Feed (Social proof)
    ├── Completions (Positive reinforcement)
    ├── New Items (Transparency)
    └── Financial Updates (Trust building)

Detailed Component Specifications

1. Authentication & Onboarding

AuthenticationSheet Component

Purpose: Single-screen auth with OAuth prioritization Headless UI: Dialog, RadioGroup Key Features:

  • Auto-detect returning users via device fingerprinting
  • Social login buttons with loading states
  • Inline validation with immediate feedback
  • Skip-ahead for demo mode

OnboardingCarousel Component

Purpose: 60-second guided setup Headless UI: Tabs (hidden), Transition Progressive Steps:

  1. Profile Setup: Name + photo (auto-import from OAuth)
  2. Household Decision: Join vs Create (large touch targets)
  3. Invite Flow: QR code + shareable link generation
  4. Feature Showcase: 4 cards with scroll-through interaction

HouseholdInvite Component

Purpose: Frictionless joining experience Features:

  • Auto-uppercase invite codes with hyphen forgiveness
  • QR scanner with camera permissions handling
  • Deep-link magic from external shares
  • Real-time validation with helpful error states

2. Dashboard (Home Screen)

PersonalStatusCard Component

Purpose: Answer "What do I need to do right now?" Headless UI: Card pattern with Button variants Smart Logic:

  • Priority algorithm: Overdue > Due Today > Financial Action > Upcoming
  • Contextual messaging based on time of day
  • Single-tap deep-linking to action item
  • Empty state with gentle encouragement

UniversalFAB Component

Purpose: Context-aware action launcher Headless UI: Menu with Transition Interaction Pattern:

  • Radial expansion on tap (iOS-style)
  • Most-used action surfaces first based on usage patterns
  • Haptic feedback on selection
  • Auto-close on outside tap or scroll

ActivityFeed Component

Purpose: Transparent social proof of household activity Features:

  • Virtualized scrolling for performance
  • Smart grouping by time and person
  • Contextual actions on tap (view details, react)
  • Gentle animations for new items

3. Chores Management

ChoresList Component

Purpose: Visual task management with minimal cognitive load Headless UI: Tabs, Checkbox, Listbox Smart Categorization:

  • Priority Tab: Overdue + Due Today (red indicators)
  • Upcoming Tab: This week's assignments
  • Available Tab: Up-for-grabs tasks with point values
  • Archive Tab: Completed items with celebration animations

QuickChoreAdd Component

Purpose: Inline task creation without modal interruption Features:

  • Autocomplete from common household tasks
  • Smart assignment based on rotation patterns
  • Default due dates based on task type
  • One-tap recurrence setting

ChoreDetail Sheet

Purpose: Progressive disclosure for complex chore setup Headless UI: Dialog, Switch, RadioGroup Accordion Sections:

  1. Assignment Logic: Single/Multiple/Rotation/Open
  2. Scheduling: Smart presets + custom options
  3. Gamification: Points, streaks, rewards (opt-in)
  4. Context: Notes, location tags, supplies needed

4. Shopping Lists

ListDirectory Component

Purpose: Multiple list management with usage prioritization Features:

  • Shopping list always pinned at top
  • Custom lists with emoji icons and member visibility
  • Recently used items surface in quick-add
  • Smart suggestions based on purchase history

SmartShoppingList Component

Purpose: Collaborative shopping with conflict prevention Headless UI: Checkbox, Command, Combobox Anti-Conflict Features:

  • "Claiming" items shows real-time to other users
  • Purchase confirmation with receipt scanning
  • Automatic expense creation prompt
  • Undo actions with 10-second grace period

ListItemComposer Component

Purpose: Intelligent item addition with context awareness Features:

  • Autocomplete from household purchase history
  • Quantity and brand suggestions
  • Store location tagging for shopping efficiency
  • Voice input with speech-to-text

5. Expense Tracking & Splitting

ExpenseOverview Component

Purpose: Financial transparency and debt visualization Headless UI: Tabs, ProgressBar pattern Trust-Building Features:

  • Net balance prominently displayed with color coding
  • Transaction history with receipt thumbnails
  • Debt graph showing money flow between members
  • Settlement reminders with customizable frequency

ExpenseCreation Sheet

Purpose: Frictionless bill splitting with smart defaults Headless UI: Dialog, RadioGroup, NumberInput Smart Splitting Logic:

  • Even split as default (covers 80% of cases)
  • Receipt OCR for automatic amount extraction
  • Category-based split suggestions (groceries, utilities)
  • Per-person cost preview before confirmation

SettlementFlow Component

Purpose: Debt resolution with verification Features:

  • Line-item breakdown of what's owed
  • Multiple payment method tracking
  • Confirmation workflow with dispute options
  • Integration hints for Venmo/PayPal/etc.

6. Group Management

HouseholdSettings Component

Purpose: Group governance and member management Headless UI: Switch, Textarea, AlertDialog Governance Features:

  • Member roles and permissions
  • House rules collaborative editing
  • Notification preferences with granular control
  • Leave/remove workflows with settlement requirements

InviteManager Component

Purpose: Growing the household safely Features:

  • Multiple invite methods (code, QR, link)
  • Invite expiration and usage tracking
  • New member onboarding delegation
  • Member approval workflow for private households

State Management Architecture

Pinia Store Structure

useHouseholdStore

  • Household metadata, members, settings
  • Real-time membership updates
  • Invite code generation and validation

useChoresStore

  • Task creation, assignment, completion
  • Rotation logic and fair assignment algorithms
  • Point tracking and gamification state

useExpensesStore

  • Expense creation and categorization
  • Balance calculations and debt tracking
  • Settlement history and dispute management

useListsStore

  • Multi-list management (shopping, todo, custom)
  • Real-time collaborative editing
  • Purchase confirmation and expense integration

useActivityStore

  • Cross-feature activity aggregation
  • Notification generation and delivery
  • Social proof and engagement metrics

Composables Strategy

useOptimisticUpdates

  • Immediate UI updates with background sync
  • Conflict resolution for simultaneous edits
  • Rollback mechanisms for failed operations

useOfflineSync

  • Operation queuing during network outages
  • Smart retry logic with exponential backoff
  • User notification of sync status

useFairness

  • Chore rotation algorithms
  • Expense splitting fairness metrics
  • Workload balance visualization

UI/UX Implementation Guidelines

Design Token System

Colors:
- Primary: Warm, trustworthy blue (#3B82F6)
- Success: Celebration green (#10B981)
- Warning: Gentle orange (#F59E0B)
- Error: Non-aggressive red (#EF4444)
- Neutral: Sophisticated grays (#64748B family)

Typography:
- Headings: Inter/SF Pro (system preference)
- Body: System font stack for optimal performance
- Monospace: JetBrains Mono for codes/numbers

Spacing:
- Base unit: 4px
- Component spacing: 16px, 24px, 32px
- Section spacing: 48px, 64px

Motion:
- Micro-interactions: 150ms ease-out
- Page transitions: 300ms ease-in-out
- Loading states: Skeleton animations

Responsive Breakpoints

  • Mobile-first: 320px base design
  • Tablet: 768px with sidebar navigation
  • Desktop: 1024px with multi-column layouts
  • Large: 1280px with dashboard widgets

Accessibility Standards

  • WCAG 2.1 AA compliance throughout
  • Keyboard navigation for all interactive elements
  • Screen reader optimization with proper ARIA labels
  • High contrast mode support
  • Reduced motion respect for vestibular disorders

Performance & Loading Strategies

Code Splitting Strategy

  • Route-based splitting for main sections
  • Component-level splitting for heavy features (receipt scanning, charts)
  • Vendor bundle optimization for frequently used libraries

Data Loading Patterns

  • Critical Path: Dashboard loads in <2 seconds
  • Progressive Enhancement: Secondary features load in background
  • Skeleton States: Immediate visual feedback while loading
  • Optimistic Caching: Predict user actions and preload data

Offline Capabilities

  • Service Worker: Cache shell and critical assets
  • IndexedDB: Store user data and pending operations
  • Background Sync: Queue operations for when connection returns
  • Conflict Resolution: Merge strategies for simultaneous edits

Migration Strategy

Phase 1: Foundation (Weeks 1-2)

  • Set up Vue 3 + Headless UI development environment
  • Implement design token system and base components
  • Create new state management architecture
  • Build authentication and onboarding flows

Phase 2: Core Features (Weeks 3-6)

  • Migrate dashboard with optimistic updates
  • Rebuild chores system with smart defaults
  • Implement new expense splitting logic
  • Create collaborative lists functionality

Phase 3: Enhancement (Weeks 7-8)

  • Add offline capabilities and sync
  • Implement advanced features (gamification, disputes)
  • Performance optimization and accessibility audit
  • User testing and feedback integration

Phase 4: Polish (Weeks 9-10)

  • Micro-interactions and animation polish
  • Advanced analytics and insights features
  • Documentation and handoff preparation
  • Gradual rollout to existing users

Success Metrics

User Experience Metrics

  • Time to First Action: <3 seconds from app open
  • Onboarding Completion: >85% reach active use
  • Daily Engagement: >60% of household members check in daily
  • Task Completion Rate: >90% of assigned chores completed on time

Technical Performance Metrics

  • First Contentful Paint: <1.5 seconds
  • Largest Contentful Paint: <2.5 seconds
  • Cumulative Layout Shift: <0.1
  • First Input Delay: <100ms

Conflict Reduction Metrics

  • Dispute Rate: <5% of expenses flagged for disputes
  • Member Retention: >95% stay in household for 30+ days
  • Positive Interactions: 80% of activity feed items are completions/additions
  • Settlement Time: Average debt resolved within 7 days

Risk Mitigation

Technical Risks

  • Data Migration: Comprehensive backup and rollback procedures
  • Performance Regression: Continuous monitoring and optimization
  • Browser Compatibility: Progressive enhancement for older browsers
  • API Changes: Versioning strategy and deprecation handling

User Experience Risks

  • Feature Parity: Ensure no critical functionality is lost
  • Learning Curve: Extensive onboarding and help documentation
  • Adoption Resistance: Gradual rollout with opt-in beta testing
  • Accessibility Gaps: Third-party accessibility auditing

Business Risks

  • User Churn: A/B testing for major changes
  • Development Timeline: Agile sprints with regular stakeholder check-ins
  • Resource Constraints: Prioritized feature development with MVP focus
  • Market Changes: Flexible architecture for future pivots

This refactor will transform the household management app from a feature-heavy tool into a delightful, frictionless experience that households actually want to use together.