From bb68261c0942ba2aee2d701afd7cef80a0bc346c Mon Sep 17 00:00:00 2001
From: Devasy Patel <110348311+Devasy23@users.noreply.github.com>
Date: Thu, 1 Jan 2026 20:39:37 +0530
Subject: [PATCH 1/3] feat: add initial documentation and tracking system for
 Jules agent

---
 .Jules/changelog.md |  68 +++++++++
 .Jules/knowledge.md | 341 ++++++++++++++++++++++++++++++++++++++++++++
 .Jules/todo.md      | 163 +++++++++++++++++++++
 3 files changed, 572 insertions(+)
 create mode 100644 .Jules/changelog.md
 create mode 100644 .Jules/knowledge.md
 create mode 100644 .Jules/todo.md

diff --git a/.Jules/changelog.md b/.Jules/changelog.md
new file mode 100644
index 0000000..37dd93e
--- /dev/null
+++ b/.Jules/changelog.md
@@ -0,0 +1,68 @@
+# Splitwiser UI/UX Changelog
+
+> All UI/UX changes made by Jules automated enhancement agent.
+
+---
+
+## [Unreleased]
+
+### Planned
+- See `todo.md` for queued tasks
+
+---
+
+## [2026-01-01] - Initial Setup
+
+### Added
+- Created Jules agent documentation and tracking system
+- `.jules/JULES_PROMPT.md` - Main agent instructions
+- `.jules/todo.md` - Task queue with prioritized improvements
+- `.jules/knowledge.md` - Codebase knowledge base
+- `.jules/changelog.md` - This changelog
+
+### Analysis Completed
+- Full audit of `web/` application structure
+- Full audit of `mobile/` application structure
+- Identified accessibility gaps
+- Identified UX improvement opportunities
+- Documented theming system patterns
+- Documented component APIs
+
+**Files Created:**
+- `.jules/JULES_PROMPT.md`
+- `.jules/todo.md`
+- `.jules/knowledge.md`
+- `.jules/changelog.md`
+
+---
+
+<!--
+## Template for future entries:
+
+## [YYYY-MM-DD] - vX.X.X
+
+### Added
+- New feature or component
+
+### Changed
+- Modifications to existing code
+
+### Fixed
+- Bug fixes
+
+### Improved
+- Performance or UX improvements
+
+### Deprecated
+- Features to be removed
+
+### Removed
+- Deleted code or features
+
+**Files Modified:**
+- `path/to/file1`
+- `path/to/file2`
+
+**Notes:**
+- Any additional context
+-->
diff --git a/.Jules/knowledge.md b/.Jules/knowledge.md
new file mode 100644
index 0000000..f6e4b5d
--- /dev/null
+++ b/.Jules/knowledge.md
@@ -0,0 +1,341 @@
+# Jules Knowledge Base
+
+> Learnings, patterns, and solutions discovered while working on Splitwiser UI/UX.
+
+---
+
+## Project Architecture
+
+### Web Application Structure
+**Date:** 2026-01-01
+**Context:** Initial codebase analysis
+
+The web app follows a clean architecture:
+```
+web/
+├── App.tsx           # Main router with protected routes
+├── components/
+│   ├── layout/       # Layout, Sidebar, ThemeWrapper
+│   └── ui/           # Reusable: Button, Card, Input, Modal, Skeleton
+├── contexts/         # AuthContext, ThemeContext
+├── pages/            # Route pages
+├── services/         # API calls
+├── constants.ts      # Theme constants (GLASSMORPHISM, NEOBRUTALISM)
+└── types.ts          # TypeScript interfaces
+```
+
+### Mobile Application Structure
+**Date:** 2026-01-01
+**Context:** Initial codebase analysis
+
+The mobile app uses Expo with React Navigation:
+```
+mobile/
+├── App.js            # Entry point with providers
+├── screens/          # All screen components
+├── navigation/       # Stack and Tab navigators
+├── context/          # AuthContext
+├── api/              # API client and service functions
+└── utils/            # Helpers (currency, balance calculations)
+```
+
+---
+
+## Theming System
+
+### Web Dual-Theme Pattern
+**Date:** 2026-01-01
+**Context:** Understanding theme switching mechanism
+
+The web app supports two themes controlled by `ThemeContext`:
+- **GLASSMORPHISM**: Modern, translucent look with blurs and gradients
+- **NEOBRUTALISM**: Bold, sharp design with hard shadows and borders
+
+**How to implement:**
+```tsx
+const { style, mode } = useTheme();
+const isNeo = style === THEMES.NEOBRUTALISM;
+
+// Apply conditional classes
+className={isNeo 
+  ? 'border-2 border-black rounded-none shadow-[4px_4px_0px_0px_rgba(0,0,0,1)]' 
+  : 'rounded-xl backdrop-blur-md border-white/20'
+}
+```
+
+**Important:** Always support BOTH themes when modifying UI components.
+
+### Color Tokens
+**Date:** 2026-01-01
+**Context:** Custom colors in tailwind.config.js
+
+```javascript
+colors: {
+  neo: {
+    main: '#8855ff',    // Primary purple
+    second: '#ff9900',  // Secondary orange  
+    accent: '#00cc88',  // Accent green
+    bg: '#f0f0f0',      // Background light
+    dark: '#1a1a1a'     // Background dark
+  }
+}
+```
+
+---
+
+## Component Patterns
+
+### Button Component Variants
+**Date:** 2026-01-01
+**Context:** Understanding Button.tsx API
+
+```tsx
+<Button 
+  variant="primary|secondary|danger|ghost"
+  size="sm|md|lg"
+  onClick={handler}
+  disabled={boolean}
+  className="additional classes"
+>
+  Content
+</Button>
+```
+
+### Card Component with Title/Action
+**Date:** 2026-01-01
+**Context:** Card.tsx supports optional header
+
+```tsx
+<Card 
+  title="Optional Title"
+  action={<Button>Action</Button>}
+  className="additional"
+>
+  {children}
+</Card>
+```
+
+### Modal Component Pattern
+**Date:** 2026-01-01
+**Context:** Modal.tsx structure
+
+```tsx
+<Modal
+  isOpen={boolean}
+  onClose={handler}
+  title="Modal Title"
+  footer={<>Cancel and Submit buttons</>}
+>
+  {content}
+</Modal>
+```
+
+---
+
+## Mobile Patterns
+
+### React Native Paper Components
+**Date:** 2026-01-01
+**Context:** Primary UI library for mobile
+
+Commonly used components:
+- `<Card>` with `<Card.Title>` and `<Card.Content>`
+- `<Avatar.Image>` and `<Avatar.Text>`
+- `<Button mode="contained|outlined|text">`
+- `<TextInput>` with label, value, onChangeText
+- `<FAB>` for floating action buttons
+- `<Portal>` and `<Modal>` for overlays
+- `<ActivityIndicator>` for loading states
+
+### Safe Area Pattern
+**Date:** 2026-01-01
+**Context:** Screens use View without SafeAreaView
+
+Most screens use `<View style={{ flex: 1 }}>` - consider wrapping in `SafeAreaView` for notched devices.
+
+---
+
+## API Response Patterns
+
+### Groups API
+**Date:** 2026-01-01
+**Context:** Group data structure from backend
+
+```typescript
+interface Group {
+  _id: string;
+  name: string;
+  currency: string;
+  joinCode: string;
+  imageUrl?: string;
+  members: GroupMember[];
+  createdAt: string;
+}
+```
+
+### Balance Summary API
+**Date:** 2026-01-01
+**Context:** Dashboard balance data
+
+```typescript
+interface BalanceSummary {
+  totalOwedToYou: number;
+  totalYouOwe: number;
+  netBalance: number;
+  groupsSummary: GroupBalanceSummary[];
+}
+```
+
+---
+
+## Known Issues & Gotchas
+
+### Image URL Validation
+**Date:** 2026-01-01
+**Context:** Avatar image handling pattern
+
+Both web and mobile use this pattern to validate image URLs:
+```javascript
+const isImage = imageUrl && /^(https?:|data:image)/.test(imageUrl);
+```
+
+Always check before rendering `<img>` or `<Avatar.Image>`.
+
+### Currency Formatting
+**Date:** 2026-01-01
+**Context:** Mobile uses utility, web uses inline
+
+- Mobile: Uses `formatCurrency()` and `getCurrencySymbol()` from `utils/currency.js`
+- Web: Uses inline template literals like `${group.currency} ${amount.toFixed(2)}`
+
+**Consider:** Standardizing currency formatting across platforms.
+
+### Framer Motion in Web
+**Date:** 2026-01-01
+**Context:** Animation library usage
+
+Common patterns:
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  whileHover={{ scale: 1.02 }}
+  transition={{ type: 'spring', stiffness: 100 }}
+/>
+```
+
+Use `AnimatePresence` for exit animations.
+
+---
+
+## Best Practices Learned
+
+### 1. Accessibility First
+Always add:
+- `aria-label` for icon-only buttons
+- `role` attributes for non-semantic elements
+- `tabIndex` for keyboard navigation
+- Focus styles for keyboard users
+
+### 2. Loading State Hierarchy
+1. Full-screen skeleton for initial load
+2. Inline loading for actions
+3. Optimistic updates where possible
+
+### 3. Error Handling
+1. Try/catch API calls
+2. Show user-friendly error messages
+3. Log errors for debugging
+4. Provide retry options
+
+### 4. Responsive Breakpoints
+Tailwind breakpoints used:
+- `sm`: 640px
+- `md`: 768px
+- `lg`: 1024px
+- `xl`: 1280px
+
+---
+
+## Errors Encountered & Solutions
+
+### Previous Agent Mistakes (Lessons Learned)
+**Date:** 2026-01-01
+**Context:** Learning from past "Palette" agent that didn't work well
+
+**Mistake 1: Wrong Package Manager**
+- **Error:** Agent used `pnpm` commands when project uses `npm`
+- **Root Cause:** Didn't verify tooling from package.json/lock files
+- **Solution:** Always check for package-lock.json (npm), yarn.lock (yarn), or pnpm-lock.yaml (pnpm) FIRST
+- **Verification:** `ls package*.json` and check for lock files
+
+**Mistake 2: Changes Too Trivial**
+- **Error:** Made insignificant changes like single ARIA labels that users didn't notice
+- **Root Cause:** Over-cautious approach with "under 50 lines" hard limit
+- **Solution:** Aim for 30-100 lines of meaningful, focused change. Each commit should be user-noticeable.
+- **Example of Good Change:** Implement complete skeleton loading system, not just one skeleton
+
+**Mistake 3: Misaligned with Project Direction**
+- **Error:** Made generic UX improvements without understanding Splitwiser's goals
+- **Root Cause:** Didn't read README or understand project trajectory
+- **Solution:** Check README, recent commits, issues. Understand Splitwiser = modern expense-splitting with dual-theme excellence
+
+**Files to Check Before Starting:**
+- `README.md` - Project vision
+- `package.json` - Available scripts and tooling
+- `.git/logs/HEAD` or recent commits - Development direction
+
+---
+
+## Project Direction & Goals
+
+### What Splitwiser Is About
+**Date:** 2026-01-01
+
+Splitwiser is focused on:
+1. **Modern expense splitting** - Making group expenses effortless
+2. **Dual-theme design** - Glassmorphism AND Neobrutalism both fully supported
+3. **Exceptional UX** - Beautiful, intuitive, delightful interactions
+4. **Cross-platform** - Web and mobile with consistent experience
+
+**NOT focused on:**
+- Generic business app features
+- Traditional accounting workflows
+- Enterprise features
+- One-off utilities
+
+**When picking tasks, ask:**
+- Does this improve expense splitting experience?
+- Does it work in BOTH themes?
+- Will users notice and appreciate this?
+- Does it move toward "modern, delightful" goal?
+
+---
+
+_Document errors and their solutions here as you encounter them._
+
+<!--
+### Error: [Error Name]
+**Date:** YYYY-MM-DD
+**Context:** What you were trying to do
+**Error Message:** The actual error
+**Solution:** How you fixed it
+**Files Affected:** List of files
+-->
+
+---
+
+## Dependencies Reference
+
+### Web
+- react-router-dom: Routing
+- framer-motion: Animations
+- recharts: Charts in Dashboard
+- lucide-react: Icons
+- tailwindcss: Styling
+
+### Mobile
+- @react-navigation/*: Navigation
+- react-native-paper: UI components
+- axios: API calls (via api/client.js)
+- expo: Platform SDK
diff --git a/.Jules/todo.md b/.Jules/todo.md
new file mode 100644
index 0000000..ae19e51
--- /dev/null
+++ b/.Jules/todo.md
@@ -0,0 +1,163 @@
+# Jules TODO List
+
+> Meaningful, user-noticeable improvements for Splitwiser. Each task should take 30-100 lines and have clear impact.
+
+**Note:** After previous agent mistakes, tasks are now grouped into meaningful units that users will actually notice.
+
+---
+
+## 🔴 High Priority (User-Facing Impact)
+
+### Web
+
+- [ ] **[ux]** Complete skeleton loading system for Dashboard
+  - Files: `web/pages/Dashboard.tsx`, `web/components/ui/Skeleton.tsx`
+  - Context: Replace "Loading stats..." text with full skeleton for cards + chart
+  - Impact: Professional loading experience, reduces perceived wait time
+  - Size: ~40 lines
+  - Added: 2026-01-01
+
+- [ ] **[ux]** Toast notification system for user actions
+  - Files: Create `web/components/ui/Toast.tsx`, integrate into actions
+  - Context: Show success/error toasts for create/delete actions (not alerts)
+  - Impact: Modern feedback without blocking user
+  - Size: ~80 lines
+  - Added: 2026-01-01
+
+- [ ] **[a11y]** Complete keyboard navigation for Groups page
+  - File: `web/pages/Groups.tsx`
+  - Context: Add keyboard handling to group cards + search + modals
+  - Impact: Full keyboard accessibility for power users
+  - Size: ~50 lines
+  - Added: 2026-01-01
+
+- [ ] **[ux]** Comprehensive empty states with illustrations
+  - Files: `web/pages/Groups.tsx`, `web/pages/Friends.tsx`, `web/pages/Dashboard.tsx`
+  - Context: Create illustrated empty states with CTAs (not just text)
+  - Impact: Guides new users, makes app feel polished
+  - Size: ~70 lines
+  - Added: 2026-01-01
+
+- [ ] **[ux]** Error boundary with retry for API failures
+  - Files: Create `web/components/ErrorBoundary.tsx`, wrap app
+  - Context: Catch errors gracefully with retry button
+  - Impact: App doesn't crash, users can recover
+  - Size: ~60 lines
+  - Added: 2026-01-01
+
+### Mobile
+
+- [ ] **[ux]** Pull-to-refresh with haptic feedback on all list screens
+  - Files: `mobile/screens/HomeScreen.js`, `mobile/screens/GroupDetailsScreen.js`
+  - Context: Add RefreshControl + Expo Haptics to main lists
+  - Impact: Native feel, users can easily refresh data
+  - Size: ~45 lines
+  - Added: 2026-01-01
+
+- [ ] **[ux]** Complete skeleton loading for HomeScreen groups
+  - File: `mobile/screens/HomeScreen.js`
+  - Context: Replace ActivityIndicator with skeleton group cards
+  - Impact: Better loading experience, less jarring
+  - Size: ~40 lines
+  - Added: 2026-01-01
+
+- [ ] **[a11y]** Complete accessibility labels for all screens
+  - Files: All screens in `mobile/screens/`
+  - Context: Add accessibilityLabel, accessibilityHint, accessibilityRole throughout
+  - Impact: Screen reader users can use app fully
+  - Size: ~60 lines across files
+  - Added: 2026-01-01
+
+---
+
+## 🟡 Medium Priority (Polish & Consistency)
+
+### Web
+
+- [ ] **[ux]** Form validation with inline feedback
+  - Files: `web/pages/Auth.tsx`, `web/pages/GroupDetails.tsx`
+  - Context: Show real-time validation with error messages under inputs
+  - Impact: Users know immediately if input is valid
+  - Size: ~50 lines
+  - Added: 2026-01-01
+
+- [ ] **[style]** Consistent hover/focus states across all buttons
+  - Files: `web/components/ui/Button.tsx`, usage across pages
+  - Context: Ensure all buttons have proper hover + focus-visible styles
+  - Impact: Professional feel, keyboard users know where they are
+  - Size: ~35 lines
+  - Added: 2026-01-01
+
+- [ ] **[ux]** Confirmation dialog for destructive actions
+  - Files: Create `web/components/ui/ConfirmDialog.tsx`, integrate
+  - Context: Confirm before deleting groups/expenses
+  - Impact: Prevents accidental data loss
+  - Size: ~70 lines
+  - Added: 2026-01-01
+
+### Mobile
+
+- [ ] **[ux]** Swipe-to-delete for expenses with undo option
+  - File: `mobile/screens/GroupDetailsScreen.js`
+  - Context: Add swipeable rows with delete action
+  - Impact: Quick expense management
+  - Size: ~55 lines
+  - Added: 2026-01-01
+
+- [ ] **[style]** Haptic feedback on all button presses
+  - Files: All button interactions across mobile
+  - Context: Add Expo.Haptics.impactAsync(Light) to buttons
+  - Impact: Tactile feedback makes app feel responsive
+  - Size: ~40 lines
+  - Added: 2026-01-01
+
+---
+
+## 🟢 Lower Priority (Nice to Have)
+
+### Web
+
+- [ ] **[ux]** Animated success celebration when settled up
+  - File: `web/pages/GroupDetails.tsx`
+  - Context: Show confetti or checkmark animation when no debts
+  - Impact: Delightful moment, positive reinforcement
+  - Size: ~45 lines
+  - Added: 2026-01-01
+
+- [ ] **[perf]** Lazy loading + code splitting for routes
+  - File: `web/App.tsx`
+  - Context: Use React.lazy for page imports
+  - Impact: Faster initial load
+  - Size: ~30 lines
+  - Added: 2026-01-01
+
+### Mobile
+
+- [ ] **[ux]** Biometric authentication option
+  - Files: `mobile/context/AuthContext.js`, add local auth
+  - Context: FaceID/TouchID for quick login
+  - Impact: Faster, more secure login
+  - Size: ~70 lines
+  - Added: 2026-01-01
+
+---
+
+## ❌ Removed (Too Trivial - Learn from Mistakes)
+
+~~Add single ARIA label to one button~~ - Too small
+~~Fix one spacing inconsistency~~ - Too insignificant  
+~~Add one hover state~~ - Not comprehensive enough
+
+---
+
+## ✅ Completed Tasks
+
+_No tasks completed yet. Move tasks here after completion._
+
+<!--
+Format:
+- [x] **[type]** Task description
+  - Completed: YYYY-MM-DD
+  - Files modified: list
+  - Impact: What users noticed
+-->

From d7c9c889224c47373b55f61ae010e0c1c76cf417 Mon Sep 17 00:00:00 2001
From: Devasy Patel <110348311+Devasy23@users.noreply.github.com>
Date: Thu, 1 Jan 2026 20:39:52 +0530
Subject: [PATCH 2/3] [jules] feat: add comprehensive guidelines for UI/UX
 enhancement tasks

---
 .Jules/JULES_PROMPT.md | 335 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 335 insertions(+)
 create mode 100644 .Jules/JULES_PROMPT.md

diff --git a/.Jules/JULES_PROMPT.md b/.Jules/JULES_PROMPT.md
new file mode 100644
index 0000000..36ce82b
--- /dev/null
+++ b/.Jules/JULES_PROMPT.md
@@ -0,0 +1,335 @@
+# Jules Scheduled Task - UI/UX Enhancement Agent
+
+## Agent Identity
+You are an autonomous UI/UX enhancement agent for the Splitwiser expense-splitting application. Your task is to make **super minor, incremental improvements** to the codebase while maintaining perfect backwards compatibility.
+
+---
+
+## Project Context
+
+### Tech Stack
+- **Web App** (`/web`): React + Vite + TypeScript + TailwindCSS + Framer Motion
+  - Uses dual theming system: `GLASSMORPHISM` and `NEOBRUTALISM`
+  - Components in `/web/components/ui/` (Button, Card, Input, Modal, Skeleton)
+  - Pages in `/web/pages/` (Auth, Dashboard, Groups, GroupDetails, Friends, Profile)
+  - Context providers for Auth and Theme
+  
+- **Mobile App** (`/mobile`): Expo/React Native + React Native Paper
+  - Screens in `/mobile/screens/`
+  - Navigation in `/mobile/navigation/`
+  - API services in `/mobile/api/`
+
+### Design Philosophy
+- Web uses modern design with two switchable themes (glassmorphism for elegance, neobrutalism for bold)
+- Mobile uses React Native Paper with Material Design principles
+- Both prioritize accessibility and responsive design
+
+---
+
+## Your Task Instructions
+
+### CRITICAL: Before Making ANY Changes
+
+1. **Verify Project Tooling** (DO THIS FIRST!)
+   ```bash
+   # Check package.json to determine package manager
+   # Look for package-lock.json (npm), yarn.lock (yarn), or pnpm-lock.yaml (pnpm)
+   # This project uses: npm (confirmed by package-lock.json presence)
+   ```
+   
+   **Available Commands for Splitwiser:**
+   - `cd web && npm install && npm run dev` - Start web dev server
+   - `cd mobile && npm install && npx expo start` - Start mobile app
+   - `cd backend && pip install -r requirements.txt && uvicorn main:app --reload` - Start backend
+   - **DO NOT use pnpm or yarn** - this project uses npm and pip
+
+2. **Understand Project Direction**
+   - Read `README.md` for project vision
+   - Check recent commits to understand current focus
+   - Review open issues/PRs to see what's being prioritized
+   - Splitwiser goal: Modern, user-friendly expense splitting with dual-theme support
+
+3. **Read the tracking files** in `.jules/`:
+   - `knowledge.md` - Understand past learnings and avoid repeating mistakes
+   - `todo.md` - Check for queued tasks to pick up
+   - `changelog.md` - Review recent changes for context
+
+4. **Analyze current state** of `web/` and `mobile/` folders
+
+### What to Fix (Priority Order)
+
+#### 🔴 Critical (Fix Immediately)
+- Accessibility issues (missing ARIA labels, keyboard navigation)
+- Text contrast issues
+- Missing loading states
+- Unhandled error states
+
+#### 🟡 High Priority
+- Inconsistent spacing/padding
+- Missing hover/active states
+- Hardcoded strings (should be constants)
+- Missing error boundaries
+
+#### 🟢 Minor Enhancements
+- Add subtle micro-animations
+- Improve empty states with illustrations/messages
+- Add skeleton loaders where missing
+- Enhance form validation feedback
+- Add haptic feedback hints for mobile
+
+---
+
+## Micro-Task Categories
+
+### Web (`/web`)
+Pick ONE task per run from each category:
+
+**1. Component Polish**
+- [ ] Add `aria-label` to icon-only buttons
+- [ ] Add `focus-visible` ring styles for keyboard navigation
+- [ ] Add subtle hover animations to Card components
+- [ ] Add loading="lazy" to images
+- [ ] Add transition effects to theme switching
+
+**2. Form UX**
+- [ ] Add input validation error shake animation
+- [ ] Add password strength indicator to signup
+- [ ] Add "show password" toggle to password fields
+- [ ] Add autocomplete attributes to form fields
+- [ ] Add form submission loading states
+
+**3. Empty States**
+- [ ] Create illustrated empty state for Groups page
+- [ ] Create illustrated empty state for Friends page
+- [ ] Add "no expenses" empty state with call-to-action
+- [ ] Add "no settlements" celebratory empty state
+
+**4. Micro-interactions**
+- [ ] Add copy-to-clipboard feedback animation
+- [ ] Add success toast on expense creation
+- [ ] Add delete confirmation animation
+- [ ] Add subtle card entrance animations
+
+**5. Responsive Fixes**
+- [ ] Fix sidebar collapse on medium screens
+- [ ] Add touch-friendly button sizes on mobile web
+- [ ] Fix modal width on small screens
+- [ ] Add pull-to-refresh indicator styling
+
+### Mobile (`/mobile`)
+Pick ONE task per run from each category:
+
+**1. Component Polish**
+- [ ] Add haptic feedback to buttons (Expo Haptics)
+- [ ] Add pull-to-refresh to list screens
+- [ ] Add swipe-to-delete on expense items
+- [ ] Add press/longPress state feedback
+- [ ] Standardize card shadows across screens
+
+**2. Form UX**
+- [ ] Add keyboard-aware scroll view to forms
+- [ ] Add input clear button to text fields
+- [ ] Add done/next keyboard buttons
+- [ ] Add automatic focus management between inputs
+
+**3. Navigation**
+- [ ] Add screen transition animations
+- [ ] Add tab bar badges for pending actions
+- [ ] Add gesture navigation support
+- [ ] Add deep linking support structure
+
+**4. Loading States**
+- [ ] Add skeleton loaders to HomeScreen groups list
+- [ ] Add skeleton loaders to GroupDetailsScreen
+- [ ] Add pull-to-refresh loading indicators
+- [ ] Add button loading states throughout
+
+**5. Accessibility**
+- [ ] Add `accessibilityLabel` to all interactive elements
+- [ ] Add `accessibilityRole` to buttons and links
+- [ ] Support dynamic text sizing
+- [ ] Add `accessibilityHint` for complex actions
+
+---
+
+## File Management Protocol
+
+### After EVERY change, update these files:
+
+#### 1. `todo.md` - Queue future improvements
+```markdown
+## Format
+- [ ] **[PRIORITY]** Brief task description
+  - File: `path/to/file`
+  - Context: Why this needs to be done
+  - Added: YYYY-MM-DD
+```
+
+#### 2. `knowledge.md` - Document learnings
+```markdown
+## Format
+### [Category] - Brief Title
+**Date:** YYYY-MM-DD
+**Context:** What you encountered
+**Solution/Learning:** What you learned
+**Files Affected:** List of files
+```
+
+#### 3. `changelog.md` - Log your changes
+```markdown
+## Format
+### [YYYY-MM-DD] - vX.X.X
+
+#### Added
+- Description of added feature
+
+#### Changed
+- Description of change
+
+#### Fixed
+- Description of fix
+
+**Files Modified:**
+- `path/to/file`
+```
+
+---
+
+## Code Quality Rules
+
+### DO
+- Make changes **meaningful but focused** (impactful but not sprawling)
+- **Verify tooling first** - Check package.json/lock files before assuming commands
+- Test that existing functionality still works
+- Follow existing code patterns and style
+- Add comments only when logic is complex
+- Use existing color tokens from `tailwind.config.js` and `constants.ts`
+- Preserve dual-theme support in web components
+- **Align with project direction** - Changes should move the project forward
+
+### DON'T
+- Make trivial changes that users won't notice (e.g., only renaming a variable)
+- **Assume tooling** - Never use pnpm/yarn without verifying the project uses them
+- Refactor large sections of code
+- Change APIs or data structures
+- Remove existing functionality
+- Add new dependencies without documenting in `knowledge.md`
+- Make changes that require database migrations
+- Break backwards compatibility
+- Make changes just for the sake of making changes
+
+---
+
+## Example Task Execution
+
+### Task: Add aria-label to icon-only Button in Sidebar
+
+**1. Identify the issue:**
+```tsx
+// Current (in Sidebar.tsx)
+<Button size="sm" variant="secondary" onClick={toggleMode}>
+  {mode === 'dark' ? <Sun size={18} /> : <Moon size={18} />}
+</Button>
+```
+
+**2. Apply fix:**
+```tsx
+// Fixed
+<Button 
+  size="sm" 
+  variant="secondary" 
+  onClick={toggleMode}
+  aria-label={mode === 'dark' ? 'Switch to light mode' : 'Switch to dark mode'}
+>
+  {mode === 'dark' ? <Sun size={18} /> : <Moon size={18} />}
+</Button>
+```
+
+**3. Update tracking files:**
+
+`todo.md` - Check off completed task, note any related tasks discovered
+
+`knowledge.md` - Document if any challenges encountered
+
+`changelog.md` - Log the change with date
+
+---
+
+## Validation Checklist
+
+Before committing any change, verify:
+- [ ] No TypeScript/ESLint errors in web
+- [ ] No React Native errors in mobile
+- [ ] Visual appearance unchanged (or improved)
+- [ ] Both themes work correctly (web)
+- [ ] Dark mode works correctly
+- [ ] No console errors or warnings
+- [ ] Tracking files updated
+- [ ] **Change is meaningful** - Users will notice and appreciate it
+- [ ] **Correct tooling used** - Verified package manager from package.json
+- [ ] **Aligns with project direction** - Improves expense-splitting UX
+
+---
+
+## Learning from Past Mistakes
+
+### ❌ Mistake 1: Assuming Tooling Without Verification
+**What Happened:** Previous agent used `pnpm` commands when project uses `npm`
+**Why It Failed:** Didn't check package.json or lock files
+**Fix:** Always verify tooling first - check for package-lock.json (npm), yarn.lock (yarn), pnpm-lock.yaml (pnpm)
+
+### ❌ Mistake 2: Changes Too Trivial/Insignificant  
+**What Happened:** Made tiny changes users didn't notice (e.g., single ARIA label)
+**Why It Failed:** Overly cautious "under 50 lines" limit led to meaningless changes
+**Fix:** Aim for 30-100 lines of focused, impactful change. Each commit should be noticeable.
+
+### ❌ Mistake 3: Not Aligned with Project Direction
+**What Happened:** Made generic UX improvements without understanding project goals
+**Why It Failed:** Didn't read project vision or recent development trajectory
+**Fix:** Check README, recent commits, and understand that Splitwiser is about modern expense-splitting with exceptional UX
+
+### ✅ What Good Changes Look Like
+- Add complete skeleton loading system to Dashboard (not just one skeleton)
+- Implement full pull-to-refresh with haptic feedback (not just the gesture)
+- Create comprehensive empty state with illustration + CTA (not just text)
+- Add entire toast notification system for user feedback
+- Implement keyboard navigation for whole page (not just one element)
+
+---
+
+## Session Start Protocol
+
+1. **Verify tooling** - Check package.json and lock files to confirm npm/yarn/pnpm
+2. **Check project direction** - Review recent commits and README for current focus
+3. Pull latest code from main branch
+4. Read `.jules/knowledge.md` for context and past mistakes
+5. Read `.jules/todo.md` for queued tasks
+6. **Pick ONE meaningful task** that:
+   - Users will actually notice and appreciate
+   - Aligns with project direction (expense-splitting UX excellence)
+   - Takes 30-100 lines of focused change (not too trivial, not too large)
+7. Make the change and verify it works
+8. Update all three tracking files
+9. Commit with descriptive message: `[jules] Brief description of change`
+
+**Red Flags (Stop and Reassess):**
+- Using commands not in package.json
+- Change feels too trivial (just renaming, adding one ARIA label)
+- Change doesn't relate to expense-splitting experience
+- Unclear if change improves user experience
+
+---
+
+## Commit Message Format
+
+```
+[jules] <type>: <brief description>
+
+<type> = fix | enhance | a11y | style | perf
+```
+
+Examples:
+- `[jules] a11y: Add aria-labels to Sidebar icon buttons`
+- `[jules] enhance: Add skeleton loader to Groups page`
+- `[jules] fix: Correct Input focus ring in dark mode`
+- `[jules] style: Improve Card hover animation timing`

From a1b8b94abb15f597250603cdb70df5bc7fc6bf99 Mon Sep 17 00:00:00 2001
From: Devasy Patel <110348311+Devasy23@users.noreply.github.com>
Date: Thu, 1 Jan 2026 21:33:50 +0530
Subject: [PATCH 3/3] fix: correct directory casing in documentation references

---
 .Jules/JULES_PROMPT.md |  6 ++---
 .Jules/changelog.md    |  8 +++---
 .Jules/knowledge.md    | 58 ++++++++++++++++++++++++++++++++++--------
 3 files changed, 54 insertions(+), 18 deletions(-)

diff --git a/.Jules/JULES_PROMPT.md b/.Jules/JULES_PROMPT.md
index 36ce82b..0cf7a95 100644
--- a/.Jules/JULES_PROMPT.md
+++ b/.Jules/JULES_PROMPT.md
@@ -49,7 +49,7 @@ You are an autonomous UI/UX enhancement agent for the Splitwiser expense-splitti
    - Review open issues/PRs to see what's being prioritized
    - Splitwiser goal: Modern, user-friendly expense splitting with dual-theme support
 
-3. **Read the tracking files** in `.jules/`:
+3. **Read the tracking files** in `.Jules/`:
    - `knowledge.md` - Understand past learnings and avoid repeating mistakes
    - `todo.md` - Check for queued tasks to pick up
    - `changelog.md` - Review recent changes for context
@@ -302,8 +302,8 @@ Before committing any change, verify:
 1. **Verify tooling** - Check package.json and lock files to confirm npm/yarn/pnpm
 2. **Check project direction** - Review recent commits and README for current focus
 3. Pull latest code from main branch
-4. Read `.jules/knowledge.md` for context and past mistakes
-5. Read `.jules/todo.md` for queued tasks
+4. Read `.Jules/knowledge.md` for context and past mistakes
+5. Read `.Jules/todo.md` for queued tasks
 6. **Pick ONE meaningful task** that:
    - Users will actually notice and appreciate
    - Aligns with project direction (expense-splitting UX excellence)
diff --git a/.Jules/changelog.md b/.Jules/changelog.md
index 37dd93e..bba97ba 100644
--- a/.Jules/changelog.md
+++ b/.Jules/changelog.md
@@ -15,10 +15,10 @@
 
 ### Added
 - Created Jules agent documentation and tracking system
-- `.jules/JULES_PROMPT.md` - Main agent instructions
-- `.jules/todo.md` - Task queue with prioritized improvements
-- `.jules/knowledge.md` - Codebase knowledge base
-- `.jules/changelog.md` - This changelog
+- `.Jules/JULES_PROMPT.md` - Main agent instructions
+- `.Jules/todo.md` - Task queue with prioritized improvements
+- `.Jules/knowledge.md` - Codebase knowledge base
+- `.Jules/changelog.md` - This changelog
 
 ### Analysis Completed
 - Full audit of `web/` application structure
diff --git a/.Jules/knowledge.md b/.Jules/knowledge.md
index f6e4b5d..d69b2bf 100644
--- a/.Jules/knowledge.md
+++ b/.Jules/knowledge.md
@@ -29,6 +29,7 @@ web/
 **Context:** Initial codebase analysis
 
 The mobile app uses Expo with React Navigation:
+
 ```
 mobile/
 ├── App.js            # Entry point with providers
@@ -37,7 +38,6 @@ mobile/
 ├── context/          # AuthContext
 ├── api/              # API client and service functions
 └── utils/            # Helpers (currency, balance calculations)
-```
 
 ---
 
@@ -45,7 +45,7 @@ mobile/
 
 ### Web Dual-Theme Pattern
 **Date:** 2026-01-01
-**Context:** Understanding theme switching mechanism
+**Context:** Understanding theme-switching mechanism
 
 The web app supports two themes controlled by `ThemeContext`:
 - **GLASSMORPHISM**: Modern, translucent look with blurs and gradients
@@ -66,14 +66,15 @@ className={isNeo
 **Important:** Always support BOTH themes when modifying UI components.
 
 ### Color Tokens
+
 **Date:** 2026-01-01
 **Context:** Custom colors in tailwind.config.js
 
-```javascript
+```js
 colors: {
   neo: {
     main: '#8855ff',    // Primary purple
-    second: '#ff9900',  // Secondary orange  
+    second: '#ff9900',  // Secondary orange
     accent: '#00cc88',  // Accent green
     bg: '#f0f0f0',      // Background light
     dark: '#1a1a1a'     // Background dark
@@ -86,6 +87,7 @@ colors: {
 ## Component Patterns
 
 ### Button Component Variants
+
 **Date:** 2026-01-01
 **Context:** Understanding Button.tsx API
 
@@ -102,6 +104,7 @@ colors: {
 ```
 
 ### Card Component with Title/Action
+
 **Date:** 2026-01-01
 **Context:** Card.tsx supports optional header
 
@@ -116,6 +119,7 @@ colors: {
 ```
 
 ### Modal Component Pattern
+
 **Date:** 2026-01-01
 **Context:** Modal.tsx structure
 
@@ -135,6 +139,7 @@ colors: {
 ## Mobile Patterns
 
 ### React Native Paper Components
+
 **Date:** 2026-01-01
 **Context:** Primary UI library for mobile
 
@@ -148,6 +153,7 @@ Commonly used components:
 - `<ActivityIndicator>` for loading states
 
 ### Safe Area Pattern
+
 **Date:** 2026-01-01
 **Context:** Screens use View without SafeAreaView
 
@@ -158,6 +164,7 @@ Most screens use `<View style={{ flex: 1 }}>` - consider wrapping in `SafeAreaVi
 ## API Response Patterns
 
 ### Groups API
+
 **Date:** 2026-01-01
 **Context:** Group data structure from backend
 
@@ -174,6 +181,7 @@ interface Group {
 ```
 
 ### Balance Summary API
+
 **Date:** 2026-01-01
 **Context:** Dashboard balance data
 
@@ -191,6 +199,7 @@ interface BalanceSummary {
 ## Known Issues & Gotchas
 
 ### Image URL Validation
+
 **Date:** 2026-01-01
 **Context:** Avatar image handling pattern
 
@@ -202,6 +211,7 @@ const isImage = imageUrl && /^(https?:|data:image)/.test(imageUrl);
 Always check before rendering `<img>` or `<Avatar.Image>`.
 
 ### Currency Formatting
+
 **Date:** 2026-01-01
 **Context:** Mobile uses utility, web uses inline
 
@@ -211,10 +221,12 @@ Always check before rendering `<img>` or `<Avatar.Image>`.
 **Consider:** Standardizing currency formatting across platforms.
 
 ### Framer Motion in Web
+
 **Date:** 2026-01-01
 **Context:** Animation library usage
 
 Common patterns:
+
 ```tsx
 <motion.div
   initial={{ opacity: 0, y: 20 }}
@@ -231,6 +243,7 @@ Use `AnimatePresence` for exit animations.
 ## Best Practices Learned
 
 ### 1. Accessibility First
+
 Always add:
 - `aria-label` for icon-only buttons
 - `role` attributes for non-semantic elements
@@ -238,17 +251,20 @@ Always add:
 - Focus styles for keyboard users
 
 ### 2. Loading State Hierarchy
+
 1. Full-screen skeleton for initial load
 2. Inline loading for actions
 3. Optimistic updates where possible
 
 ### 3. Error Handling
+
 1. Try/catch API calls
 2. Show user-friendly error messages
 3. Log errors for debugging
 4. Provide retry options
 
 ### 4. Responsive Breakpoints
+
 Tailwind breakpoints used:
 - `sm`: 640px
 - `md`: 768px
@@ -260,27 +276,32 @@ Tailwind breakpoints used:
 ## Errors Encountered & Solutions
 
 ### Previous Agent Mistakes (Lessons Learned)
+
 **Date:** 2026-01-01
 **Context:** Learning from past "Palette" agent that didn't work well
 
 **Mistake 1: Wrong Package Manager**
+
 - **Error:** Agent used `pnpm` commands when project uses `npm`
 - **Root Cause:** Didn't verify tooling from package.json/lock files
 - **Solution:** Always check for package-lock.json (npm), yarn.lock (yarn), or pnpm-lock.yaml (pnpm) FIRST
 - **Verification:** `ls package*.json` and check for lock files
 
 **Mistake 2: Changes Too Trivial**
+
 - **Error:** Made insignificant changes like single ARIA labels that users didn't notice
 - **Root Cause:** Over-cautious approach with "under 50 lines" hard limit
 - **Solution:** Aim for 30-100 lines of meaningful, focused change. Each commit should be user-noticeable.
 - **Example of Good Change:** Implement complete skeleton loading system, not just one skeleton
 
 **Mistake 3: Misaligned with Project Direction**
+
 - **Error:** Made generic UX improvements without understanding Splitwiser's goals
 - **Root Cause:** Didn't read README or understand project trajectory
 - **Solution:** Check README, recent commits, issues. Understand Splitwiser = modern expense-splitting with dual-theme excellence
 
 **Files to Check Before Starting:**
+
 - `README.md` - Project vision
 - `package.json` - Available scripts and tooling
 - `.git/logs/HEAD` or recent commits - Development direction
@@ -290,13 +311,24 @@ Tailwind breakpoints used:
 ## Project Direction & Goals
 
 ### What Splitwiser Is About
+
 **Date:** 2026-01-01
 
-Splitwiser is focused on:
+Splitwiser is focused on (per README):
 1. **Modern expense splitting** - Making group expenses effortless
-2. **Dual-theme design** - Glassmorphism AND Neobrutalism both fully supported
-3. **Exceptional UX** - Beautiful, intuitive, delightful interactions
-4. **Cross-platform** - Web and mobile with consistent experience
+2. **Group management** - Create and manage expense groups
+3. **Real-time synchronization** - Keep data synced across devices
+4. **Secure authentication** - JWT-based auth with refresh tokens
+5. **Receipt management** - Track and store receipt images
+6. **Debt simplification** - Minimize number of transactions
+7. **Multi-currency support** - Handle different currencies
+8. **Exceptional UX** - Beautiful, intuitive, delightful interactions
+9. **Cross-platform** - Web (React/Vite/TypeScript) and mobile (Expo/React Native)
+
+**Current Implementation Details:**
+- Web app uses dual-theme design system (Glassmorphism & Neobrutalism)
+- Mobile uses React Native Paper (Material Design)
+- Backend: FastAPI + MongoDB
 
 **NOT focused on:**
 - Generic business app features
@@ -306,15 +338,16 @@ Splitwiser is focused on:
 
 **When picking tasks, ask:**
 - Does this improve expense splitting experience?
-- Does it work in BOTH themes?
+- For web: Does it work in BOTH themes?
 - Will users notice and appreciate this?
-- Does it move toward "modern, delightful" goal?
+- Does it align with the README's core features?
 
 ---
 
 _Document errors and their solutions here as you encounter them._
 
-<!--
+```markdown
+<!-- Template for documenting errors:
 ### Error: [Error Name]
 **Date:** YYYY-MM-DD
 **Context:** What you were trying to do
@@ -322,12 +355,14 @@ _Document errors and their solutions here as you encounter them._
 **Solution:** How you fixed it
 **Files Affected:** List of files
 -->
+```
 
 ---
 
 ## Dependencies Reference
 
 ### Web
+
 - react-router-dom: Routing
 - framer-motion: Animations
 - recharts: Charts in Dashboard
@@ -335,6 +370,7 @@ _Document errors and their solutions here as you encounter them._
 - tailwindcss: Styling
 
 ### Mobile
+
 - @react-navigation/*: Navigation
 - react-native-paper: UI components
 - axios: API calls (via api/client.js)