Punchie Pass

Punchie Pass — an AI-powered punch-card habit tracker that brings joy, motivation, and nostalgia to your daily routines.

Comment

Inspiration

Punchie Pass was inspired by the nostalgic satisfaction of collecting punches on coffee shop loyalty cards. We wanted to bring that tangible, rewarding feeling to digital habit tracking. The idea came from recognizing that most habit trackers are boring; we wanted something that makes building better routines feel like collecting rewards at your favorite café. The physical act of punching a hole in a card creates a moment of accomplishment, and we sought to recreate that satisfying interaction digitally, and the playful fun UI makes it easy and fun to track and build habits.

What it does

Punchie Pass is a delightful habit-tracking web application that transforms goal-setting into an engaging visual experience. Users create custom digital punch cards for their habits, complete with beautiful backgrounds, personalized icons, and customizable layouts. Each time they complete a habit, they "punch" their card with a satisfying interactive experience featuring a custom hole-punch cursor.

Key features include:

  • Custom Punch Cards: Choose from multiple card designs (Windows, Lace, Plaid, Camera themes) with personalized titles, descriptions, and icons
  • Interactive Punching Experience: Click to punch holes with a custom animated hole-punch cursor that follows your mouse
  • AI-Powered Features:
    • Transform broad goals into actionable habits using Google Gemini AI
    • Get personalized reward suggestions for completing habits
    • Receive empathetic AI coaching feedback on weekly reflections
  • Visual Progress Tracking: See your progress at a glance with beautifully designed cards that show filled vs. empty punch slots
  • Sharing & Social: Generate QR codes to share completed punch passes, download cards as images, and celebrate achievements
  • Reflection Journaling: Write weekly reflections and receive AI-powered insights and suggestions
  • Dashboard Overview: View all habits in an elegant carousel interface with statistics on total punches and completed habits

How we used AI

AI is built into Punchie Pass in a way that directly supports behavior change instead of being just a gimmick. We use the Google Gemini API in three core flows:

  1. Goal → Habit Generator
    Users can type a vague, high-level goal like “I want to stop cramming for exams” or “I want to be more consistent with working out.” This text is sent to Gemini with a prompt that asks it to:

    • Break the goal into concrete, trackable habits
    • Suggest a reasonable frequency (daily, weekly, etc.)
    • Provide a short description for each habit
      The response is parsed into a list of structured habit suggestions that users can choose from with one click to instantly create a punch card.

  2. AI Reward Suggestions
    When creating a habit, users can click an “AI suggestions” button for rewards. We send the habit title (and sometimes the time window) to Gemini and ask for:

    • Student-friendly, low-cost rewards
    • A mix of self-care, fun, and motivating incentives
      The returned suggestions show up as a clickable list. Choosing one fills the reward field automatically, making it easier to pair habits with meaningful, realistic incentives.

  3. Reflection AI Coach / Chatbot
    At the end of the week, users can write a reflection about how their habits went. We send:

    • The reflection text
    • Context about the user’s habits (titles, target punches, current punches)
      to Gemini with instructions to respond as an empathetic coach. The AI:
    • Highlights what went well
    • Validates challenges
    • Suggests a few specific next steps
      The feedback is shown as a main “coach message” plus a list of numbered suggestions. From there, we can extend this into a lightweight chat experience where users can continue asking the AI follow-up questions about their routines.

We also added:

  • Error and fallback handling so reflections are still saved even if the AI is unavailable
  • Prompt tuning to keep the tone supportive, student-centered, and concise

How we built it

Frontend:

  • React 19 with Vite for fast development and hot module replacement
  • Framer Motion for smooth animations and transitions (carousel, modals, card interactions)
  • Tailwind CSS 4 for modern, responsive styling
  • Zustand for lightweight state management
  • React Router for navigation

Backend & Services:

  • Firebase (Authentication, Firestore, Storage) for user data and persistence
  • Google Gemini AI API for habit generation, reward suggestions, and reflection analysis
  • Custom cursor implementation using React hooks and CSS positioning

Key Technical Implementations:

  • Custom hole-punch cursor that follows mouse movement and changes on click
  • Dynamic card layout system with precise positioning for text, icons, and punch grids
  • QR code generation and sharing using Firebase Storage
  • Image generation using html2canvas for shareable card exports
  • Real-time habit synchronization with Firestore
  • Responsive carousel with infinite scroll and smooth animations

Development Tools:

  • Vite for fast builds and development server
  • ESLint for code quality
  • Day.js for date handling

Challenges we ran into

  1. Custom Cursor Implementation: Creating a custom hole-punch cursor that follows the mouse smoothly while maintaining performance required careful event handling and requestAnimationFrame optimization. We had to hide the default cursor and manually track mouse position.

  2. Dynamic Card Layout System: Each punch card design needed precise positioning for titles, descriptions, icons, and punch grids. We built a flexible layout configuration system that maintains visual consistency.

  3. Animation Performance: The carousel with multiple cards and the zoom modal animations needed optimization to run smoothly on lower-end devices. We used Framer Motion's spring physics and careful z-index management.

  4. AI Prompt Design & Integration: Getting Gemini to return structured, consistent, and useful outputs for different use cases (goal → habits, rewards, reflections) took several iterations. We had to experiment with prompt wording, add guardrails, and handle cases where the AI output was either too generic or too verbose.

Accomplishments that we're proud of

  1. Delightful User Experience: The custom hole-punch cursor and satisfying punch interaction create a unique, memorable experience that makes habit tracking genuinely fun.

  2. Beautiful Visual Design: We created multiple card themes with carefully crafted layouts that feel premium and personalized, not generic.

  3. AI-Powered Intelligence: Successfully integrated Gemini AI to provide genuinely helpful habit suggestions, reward ideas, and empathetic coaching feedback that feels personal and actionable.

  4. Smooth Animations: Built a polished carousel interface with smooth transitions, proper focus management, and intuitive navigation that feels native.

  5. Complete Feature Set: Delivered a full-stack application with authentication, data persistence, sharing capabilities, and AI features—all working seamlessly together.

  6. Responsive Design: The app works beautifully across different screen sizes with thoughtful mobile and desktop layouts.

  7. Performance: Despite rich animations and real-time features, the app maintains fast load times and smooth interactions.

What we learned

  1. Firebase Integration: Learned to structure Firestore data efficiently, handle real-time updates, and manage Firebase Storage for file uploads and QR code generation.

  2. AI API Integration: Gained experience working with the Google Gemini API, including:

    • Prompt engineering for different use cases (habits, rewards, reflections)
    • Parsing and normalizing AI responses into structured data
    • Handling errors, rate limits, and fallback strategies so the core app still works without AI

  3. CSS Positioning & Layout: Developed expertise in absolute positioning, transforms, and responsive design to create pixel-perfect card layouts.

  4. User Experience Design: Learned the importance of micro-interactions, visual feedback, and making mundane tasks (habit tracking) feel rewarding and engaging. We also saw how AI can enhance UX when it’s integrated thoughtfully instead of taking over the experience.

What's next for Punchie Pass

  1. Social Features: Debugging QR code sharing and allowing users to share habits with friends, create group challenges, and celebrate each other's progress.

  2. Advanced Analytics: Add detailed progress charts, streak tracking, and insights into habit patterns over time.

  3. More Card Designs: Expand the library of punch card themes and allow users to generate and upload icons.

  4. Mobile App: Develop native iOS and Android apps for on-the-go habit tracking with push notifications.

  5. Habit Templates: Pre-built habit templates for common goals (fitness, study, wellness) to help users get started quickly, potentially powered by AI suggestions.

  6. Reminder System: Smart notifications that adapt to user behavior and help maintain consistency.

  7. UI/UX Improvements: Continue polishing interactions, layouts, and AI flows to make the site smoother and more intuitive.

Built With

Share this project:

Updates