Kachuful Scorer - Antigravity Development Guide

Project: Kachuful Card Game Scoring Application
AI Agent: Antigravity by Google Deepmind
Purpose: Step-by-step guide for building the app using Antigravity

---

🎯 Project Overview

This application tracks scores for Kachuful (also called Judgement), a trick-taking card game popular in India. The app automates score calculation, manages rounds, and provides statistics.

Key Game Mechanics:

• 2-10 players predict exact number of tricks they'll win
• Scoring: 10 + predicted tricks if accurate, 0 if wrong
• Dealer restriction: Last bidder can't make total bids equal total tricks
• Trump rotates: Spades → Diamonds → Clubs → Hearts → No Trump

---

📋 Reference Documents

Before starting implementation, review these planning documents:

1. PRD - Complete requirements and game rules
2. Roadmap - 8-week development plan

---

🚀 Phase 1: MVP Development (Weeks 1-3)

Step 1: Project Initialization

Prompt for Antigravity:

Create a new Kachuful scoring app using Vite + React + TypeScript.

Requirements:
- Initialize project with: npx create-vite@latest ./ --template react-ts
- Setup Tailwind CSS for styling
- Create folder structure:
  /src
    /components  (UI components)
    /lib         (game logic)
    /types       (TypeScript types)
    /hooks       (custom React hooks)
    /styles      (global styles)
- Create design system with tokens for colors, spacing, typography

Follow web application best practices with premium, modern aesthetics.

Expected Deliverables:

• Working React + TypeScript + Tailwind setup
• Folder structure created
• Initial design-tokens.css or equivalent

---

Step 2: Core Game Logic

Prompt for Antigravity:

Implement the core Kachuful game logic in /src/lib/game-logic.ts

Requirements:
1. Create TypeScript types/interfaces:
   - Player
   - Round
   - GameState
   - ScoringVariant

2. Implement functions:
   - calculateScore(predicted: number, actual: number, variant: ScoringVariant): number
   - validateBids(bids: number[], totalTricks: number, dealerIndex: number): boolean
   - getTrumpSuit(roundNumber: number): 'spades' | 'diamonds' | 'clubs' | 'hearts' | 'none'
   - getCardsDealt(roundNumber: number, totalRounds: number): number
   - isGameComplete(currentRound: number, totalRounds: number): boolean

3. Default scoring: 10 + predicted if exact match, 0 if wrong
4. Dealer restriction: Total bids cannot equal total tricks available
5. Trump rotation: ♠️ → ♦️ → ♣️ → ♥️ → No Trump (cycles)

Write comprehensive unit tests for all logic.

Expected Deliverables:

• game-logic.ts with all functions
• Type definitions in types/game.ts
• Unit tests passing

---

Step 3: Game Setup Screen

Prompt for Antigravity:

Create the Game Setup screen component in /src/components/GameSetup.tsx

Requirements:
1. Form to collect:
   - Number of players (2-10, dropdown or stepper)
   - Player names (dynamic input fields)
   - Scoring variant (default: "10 + Predicted")
   - Optional: Starting hand size, total rounds

2. Validation:
   - All players must have names
   - No duplicate names
   - At least 2 players

3. Design:
   - Card-game aesthetic with card suit icons
   - Premium colors: deep blue/purple gradients with gold accents
   - Glassmorphism effects
   - Large, touch-friendly inputs for mobile
   - Smooth micro-animations on interactions

4. On submit: Initialize game state and navigate to bidding screen

Use Tailwind CSS and follow modern web design principles.

Expected Deliverables:

• GameSetup.tsx component
• Form validation working
• Beautiful, responsive UI

---

Step 4: Bidding Screen

Prompt for Antigravity:

Create the Bidding Screen in /src/components/BiddingScreen.tsx

Requirements:
1. Display current round info:
   - Round number (e.g., "Round 3 of 13")
   - Cards dealt this round
   - Trump suit (with colored suit icon)
   - Current dealer

2. Bid entry for each player:
   - Show player name
   - Buttons 0-[max tricks] for bid selection
   - Highlight selected bid
   - Disable invalid bids for dealer (dealer restriction)

3. Validation:
   - Show warning if dealer's bid makes total = total tricks
   - All players must bid before proceeding

4. Premium design:
   - Large bid buttons (0-13)
   - Smooth animations when selecting
   - Progress indicator (3 of 4 players bid)
   - Visual feedback for dealer restriction

5. On complete: Move to tricks entry screen

Make it mobile-first with excellent touch targets.

Expected Deliverables:

• BiddingScreen.tsx component
• Dealer restriction validation working
• Polished UI with animations

---

Step 5: Tricks Entry & Scoring

Prompt for Antigravity:

Create the Tricks Entry screen in /src/components/TricksEntry.tsx

Requirements:
1. After round is played physically, players enter tricks won
2. For each player:
   - Show name, bid amount
   - Stepper or number input for tricks won (0-[cards dealt])
   - Visual indicator if prediction matched

3. Auto-calculate scores when all tricks entered:
   - Use scoring algorithm from game-logic.ts
   - Show individual round scores
   - Update cumulative scores

4. Display:
   - Success indicator (green checkmark) if bid matched
   - Failure indicator (red X) if bid missed
   - Points earned this round

5. Action buttons:
   - "Next Round" → move to next bidding round
   - "View Scoreboard" → see full scores

Premium design with celebratory animations for successful predictions.

Expected Deliverables:

• TricksEntry.tsx component
• Score calculation integrated
• Smooth transitions

---

Step 6: Scoreboard

Prompt for Antigravity:

Create the Scoreboard component in /src/components/Scoreboard.tsx

Requirements:
1. Table layout showing:
   - Player names (column headers or row headers)
   - Each round as row/column
   - Bid vs Actual for each round (e.g., "3/3 ✓" or "2/5 ✗")
   - Round score for each player
   - Cumulative total score (bold/highlighted)

2. Visual features:
   - Highlight current leader (gold border/background)
   - Color-code successful vs failed predictions
   - Responsive table (horizontal scroll on mobile if needed)
   - Sort by rank option

3. Summary stats:
   - Total rounds played
   - Rounds remaining
   - Current leader

4. Actions:
   - Continue to next round
   - View detailed breakdown
   - End game (if final round)

Use premium table design with card-game theming.

Expected Deliverables:

• Scoreboard.tsx component
• Responsive table layout
• Leader highlighting

---

Step 7: Game State Management

Prompt for Antigravity:

Implement game state management using React Context or Zustand

Requirements:
1. Create global game state including:
   - Players array
   - Current round number
   - Rounds array (history of bids/tricks/scores)
   - Game settings (scoring variant, total rounds)
   - Game status (setup, bidding, playing, complete)

2. Actions:
   - initializeGame(settings)
   - submitBids(bids)
   - submitTricks(tricks)
   - nextRound()
   - endGame()
   - resetGame()

3. Persistence:
   - Save state to localStorage on every update
   - Load state on app mount
   - Handle corrupted data gracefully

4. Type safety:
   - Full TypeScript types for state and actions
   - Immutable updates

Choose between Context API or Zustand based on complexity.

Expected Deliverables:

• State management setup
• LocalStorage persistence working
• Type-safe state updates

---

Step 8: Routing & Integration

Prompt for Antigravity:

Integrate all components with routing using React Router

Requirements:
1. Routes:
   / → Home/Game Setup
   /bidding → Bidding Screen
   /tricks → Tricks Entry
   /scoreboard → Scoreboard
   /results → Final Results (winner announcement)

2. Navigation guards:
   - Redirect to setup if no active game
   - Prevent accessing future rounds

3. Layout:
   - Shared header with game info (round, scores)
   - Navigation breadcrumbs
   - Exit/Quit game button

4. Transitions:
   - Smooth page transitions
   - Loading states where needed

Setup proper routing with state-aware navigation.

Expected Deliverables:

• React Router setup
• All screens connected
• Proper navigation flow

---

Step 9: Winner Declaration

Prompt for Antigravity:

Create the Final Results screen in /src/components/FinalResults.tsx

Requirements:
1. Display after last round:
   - 🏆 Winner announcement with celebration
   - Final rankings (1st, 2nd, 3rd...)
   - Total scores for all players
   - Game statistics:
     - Most successful predictions
     - Highest single-round score
     - Average bid accuracy

2. Visual design:
   - Confetti or celebration animation
   - Trophy icon for winner
   - Medal icons for top 3
   - Premium card-reveal animation

3. Actions:
   - Save Game (to history)
   - Play Again (new game with same players)
   - New Game (fresh setup)
   - View Full Scoreboard

Make it feel rewarding with animations and effects.

Expected Deliverables:

• FinalResults.tsx component
• Winner celebration
• Game completion flow

---

Step 10: MVP Testing & Polish

Prompt for Antigravity:

Polish the MVP for initial release:

1. Error Handling:
   - Add error boundaries
   - Handle invalid states gracefully
   - Show user-friendly error messages

2. Loading States:
   - Skeleton loaders where appropriate
   - Smooth transitions between screens

3. Responsive Design:
   - Test on mobile (375px)
   - Test on tablet (768px)
   - Test on desktop (1024px+)

4. Accessibility:
   - Add ARIA labels
   - Keyboard navigation support
   - Color contrast compliance

5. Performance:
   - Optimize animations (60 FPS)
   - Code splitting for routes
   - Image optimization

6. Deploy:
   - Build production bundle
   - Deploy to Vercel/Netlify
   - Test deployment

Ensure everything works smoothly end-to-end.

Expected Deliverables:

• Polished, production-ready MVP
• Deployed app with working URL
• Bug-free gameplay

---

🎨 Design Guidelines for Antigravity

When prompting Antigravity for UI components, always include these design requirements:

Visual Aesthetics

• Premium feel: Vibrant gradients, glassmorphism, subtle shadows
• Card game theme: Use ♠️ ♥️ ♦️ ♣️ suit symbols as visual elements
• Modern: 2025-style design, not dated or basic
• Dark mode: Default to dark theme with rich colors

Color Palette

• Primary: Deep blue (#1E3A8A) to purple (#7C3AED) gradient
• Accent: Gold (#F59E0B) for highlights and leader
• Success: Green (#10B981) for correct predictions
• Error: Red (#EF4444) for wrong predictions
• Suits: Red for ♥️♦️, Black for ♠️♣️

Typography

• Headings: Bold, large (2xl-4xl)
• Body: Clean, readable (base-lg)
• Numbers/Scores: Monospace or tabular figures

Animations

• Micro-interactions: Button hovers, clicks
• Page transitions: Smooth fade/slide
• Celebration: Confetti on winner reveal

---

📦 Phase 2-4: Future Enhancements

When ready to extend beyond MVP, use these prompts:

Game History

Add game history feature:
- Save completed games to IndexedDB
- Show list of past games with date, players, winner
- View detailed scoreboard of past games
- Delete games
- Search/filter by player name or date

Player Statistics

Create player statistics dashboard:
- Win rate per player
- Average score
- Bid accuracy (% of rounds where prediction matched)
- Best performance (highest score)
- Head-to-head records
- Charts using Chart.js or Recharts

Dark Mode Toggle

Implement dark/light mode toggle:
- Use Tailwind dark: classes
- Persist preference in localStorage
- Smooth transition between modes
- Update all components for both themes

Export & Sharing

Add export features:
- Export scoreboard as PDF (use jsPDF)
- Export as CSV for Excel
- Generate shareable link with game state
- Copy scoreboard to clipboard

PWA Features

Convert to Progressive Web App:
- Add manifest.json
- Create service worker for offline support
- Enable "Add to Home Screen"
- Cache assets for performance
- Test offline functionality

---

🧪 Testing Prompts

Unit Testing

Write comprehensive unit tests for game logic:
- Test all scoring variants
- Test dealer restriction validation
- Test trump rotation
- Test edge cases (0 bids, max bids)
- Use Vitest or Jest
- Aim for 90%+ code coverage

Integration Testing

Add integration tests for user flows:
- Complete game flow (setup → bidding → tricks → results)
- State persistence and restoration
- Navigation between screens
- Error scenarios
- Use React Testing Library

---

🛠️ Troubleshooting

Common Issues & Prompts

Issue: Scoring calculation incorrect

Debug the scoring calculation in game-logic.ts:
- Add detailed console logs for predicted vs actual
- Verify formula: 10 + predicted (if match), else 0
- Test with edge case: 0 predicted, 0 actual → should be 10 points
- Check for off-by-one errors

Issue: Mobile UI not responsive

Fix mobile responsiveness:
- Use Tailwind responsive classes (sm:, md:, lg:)
- Test bid buttons are min 44px touch targets
- Ensure tables scroll horizontally on small screens
- Check text sizes are readable (min 16px)
- Test on iPhone SE (375px width)

Issue: State not persisting

Debug localStorage persistence:
- Console log state before saving
- Check localStorage in DevTools
- Verify JSON serialization doesn't lose data
- Add error handling for QuotaExceeded
- Test state restoration on page reload

---

📱 Deployment Checklist

Before launching, verify with Antigravity:

Prepare for production deployment:

1. Build optimization:
   - Run 'npm run build'
   - Verify bundle size < 500KB
   - Check for console errors in production build

2. Performance:
   - Run Lighthouse audit (target 90+ score)
   - Optimize images (use WebP)
   - Enable code splitting

3. SEO & Meta:
   - Add proper title and meta description
   - Include Open Graph tags
   - Add favicon and app icons

4. Security:
   - No API keys exposed
   - Proper CORS if applicable
   - HTTPS enabled

5. Deploy to Vercel:
   - Connect GitHub repo
   - Configure deployment settings
   - Test production URL

6. Post-deployment:
   - Test on real devices
   - Share with beta users
   - Monitor for errors (add Sentry if needed)

---

🎯 Quick Command Reference

# Initialize project
npx create-vite@latest ./ --template react-ts

# Install dependencies
npm install

# Add Tailwind
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

# Install additional packages
npm install react-router-dom zustand  # or use Context API
npm install lucide-react  # for icons

# Development
npm run dev

# Build
npm run build

# Preview build
npm run preview

# Deploy to Vercel
npx vercel

# Run tests
npm run test

---

📚 Additional Resources

Share these with Antigravity when relevant:

• Kachuful Wikipedia
• React Documentation
• Tailwind CSS Docs
• Vite Guide

---

✅ Success Criteria

Before considering MVP complete:

• Full game playable without errors
• Scoring 100% accurate (verified manually)
• Mobile responsive (tested on phone)
• Dark mode with premium aesthetics
• LocalStorage persistence working
• 5+ test games completed successfully
• Deployed and accessible via URL

---

🚀 Next Steps

1. Start with Step 1: Project Initialization
2. Work through steps sequentially
3. Test thoroughly after each step
4. Use this guide as reference throughout development
5. After MVP, proceed to Phase 2 enhancements

Ready to begin? Start with the project initialization prompt above!