diff --git a/.Jules/JULES_PROMPT.md b/.Jules/JULES_PROMPT.md new file mode 100644 index 0000000..0cf7a95 --- /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) + +``` + +**2. Apply fix:** +```tsx +// Fixed + +``` + +**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] : + + = 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` diff --git a/.Jules/changelog.md b/.Jules/changelog.md new file mode 100644 index 0000000..bba97ba --- /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` + +--- + + diff --git a/.Jules/knowledge.md b/.Jules/knowledge.md new file mode 100644 index 0000000..d69b2bf --- /dev/null +++ b/.Jules/knowledge.md @@ -0,0 +1,377 @@ +# 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 + +```js +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 + +``` + +### Card Component with Title/Action + +**Date:** 2026-01-01 +**Context:** Card.tsx supports optional header + +```tsx +Action} + className="additional" +> + {children} + +``` + +### Modal Component Pattern + +**Date:** 2026-01-01 +**Context:** Modal.tsx structure + +```tsx +Cancel and Submit buttons} +> + {content} + +``` + +--- + +## Mobile Patterns + +### React Native Paper Components + +**Date:** 2026-01-01 +**Context:** Primary UI library for mobile + +Commonly used components: +- `` with `` and `` +- `` and `` +- `