.copilot-instructions-style-guide

Instruction file imported from Lajuro/birthday_bet_counter (.github/instructions/.copilot-instructions-style-guide.instructions.md). Copyright stays with the author.

Provide project context and coding guidelines that AI should follow when generating code, answering questions, or reviewing changes.# Copilot Instructions - Birthday Bet Counter

Project Overview

This is a React/Next.js application for tracking baby birth predictions with a celebration mode when the baby is born. The app features a dynamic UI that adapts based on whether the baby has been born, using a pink/purple celebration theme vs. an indigo/slate waiting theme.

Architecture & Tech Stack

• Framework: Next.js 15.2.3 with App Router
• Language: TypeScript with strict typing
• Styling: Tailwind CSS with custom CSS for animations
• UI Components: shadcn/ui components
• Icons: Lucide React
• State Management: React Context (AuthContext)
• Backend: Firebase (Auth + Firestore)
• Fonts: Geist Sans & Geist Mono

Design System & Style Guide

Color Schemes

Normal Mode (Baby not born yet)

• Primary: Indigo (600-700)
• Secondary: Purple (600-700)
• Background: Slate gradients (950-900)
• Text: Slate (700 light, 300 dark)
• Accents: Indigo/Purple gradients

Celebration Mode (Baby born)

• Primary: Pink (600-700)
• Secondary: Purple (600-700)
• Background: Pink/Purple/Indigo gradients (50-100)
• Text: Pink (700-900 light, 300-400 dark)
• Accents: Pink/Purple/Indigo celebration colors

Responsive Design Principles

Breakpoints (Tailwind standard)

• Mobile: Default (< 640px)
• SM: 640px+ (sm:)
• MD: 768px+ (md:)
• LG: 1024px+ (lg:)
• XL: 1280px+ (xl:)

Mobile-First Approach

• Always start with mobile styles
• Use progressive enhancement with breakpoint prefixes
• Minimum touch targets: 44px (mobile-menu-button class)
• Text scaling: Use responsive text classes (text-sm sm:text-base md:text-lg)

Spacing & Layout

• Mobile padding: p-2 sm:p-4 (8px -> 16px)
• Desktop padding: lg:p-6 xl:p-8 (24px -> 32px)
• Container max-width: max-w-7xl mx-auto
• Grid gaps: gap-2 sm:gap-3 md:gap-4 (8px -> 12px -> 16px)

Component Patterns

Card Components

// Standard card pattern
<Card className="bg-gradient-to-br from-pink-50 via-purple-50 to-indigo-50 dark:from-pink-950/30 shadow-xl border-pink-200/50">
  <CardHeader className="text-center py-4 sm:py-6 px-3 sm:px-4 lg:px-6">
    // Header content
  </CardHeader>
  <CardContent className="relative pb-4 sm:pb-6 px-3 sm:px-4 lg:px-6">
    // Main content
  </CardContent>
</Card>

Button Patterns

// Primary button
<Button className="bg-gradient-to-r from-indigo-600 to-purple-600 hover:from-indigo-700 hover:to-purple-700 text-white">

// Ghost button (context-aware)
<Button variant="ghost" className={`${babyBorn ? 'text-pink-700 hover:bg-pink-50' : 'text-slate-700 hover:bg-indigo-50'}`}>

Grid Layouts

// Responsive counter grid
<div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-2 sm:gap-3 md:gap-4">

// Responsive card grid
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2 sm:gap-3">

Typography Scale

Headings

• H1: text-xl sm:text-2xl md:text-3xl lg:text-4xl xl:text-5xl
• H2: text-lg sm:text-xl md:text-2xl lg:text-3xl
• H3: text-base sm:text-lg md:text-xl
• Body: text-sm sm:text-base
• Small: text-xs sm:text-sm
• Tiny: text-[10px] sm:text-xs

Font Weights

• Bold: font-bold (headings, important numbers)
• Semibold: font-semibold (sub-headings)
• Medium: font-medium (labels, navigation)
• Normal: font-normal (body text)

Animation & Motion

Custom Animations (defined in CSS files)

• baby-born-heart: Pulsing heart animation
• baby-born-rainbow: Rainbow text gradient animation
• baby-born-badge-animated: Badge entrance animation
• baby-born-counter-seconds: Number update animation

Transition Classes

• Standard: transition-all duration-300
• Fast: transition-colors duration-200
• Smooth: transition-transform duration-500

Accessibility

• Respect prefers-reduced-motion: reduce
• Always provide alternative for motion-sensitive users

Mobile Menu Pattern

Structure

{
  mobileMenuOpen && (
    <>
      {/* Backdrop */}
      <div className="mobile-menu-backdrop fixed inset-0 bg-black/50 backdrop-blur-sm z-40" />

      {/* Content */}
      <div className="mobile-menu-content fixed top-16 left-0 right-0 z-50 backdrop-blur-lg">
        {/* Menu items */}
      </div>
    </>
  );
}

Required Features

• Backdrop click to close
• ESC key to close
• Prevent body scroll when open
• Smooth animations
• Touch-friendly targets (mobile-menu-item class)

Form Patterns

Input Components

<div className="space-y-2">
  <Label htmlFor="input" className="text-sm font-medium">
  <Input
    className="h-12"
    placeholder="..."
  />
</div>

Form Layout

• Use space-y-4 for form field spacing
• Add proper labels and accessibility
• Responsive button sizing (h-10 sm:h-12)

Icon Usage

Size Standards

• Small: h-4 w-4 (16px)
• Medium: h-5 w-5 (20px)
• Large: h-6 w-6 (24px)
• Avatar: h-8 w-8 or h-10 w-10

Context Colors

• Use theme-aware colors: ${babyBorn ? 'text-pink-600' : 'text-indigo-600'}

File Organization

CSS Files (import order in layout.tsx)

1. globals.css - Global styles & CSS variables
2. custom-scrollbar.css - Scrollbar customization
3. mobile-responsive.css - Mobile-specific responsive fixes
4. mobile-menu.css - Mobile menu animations & styles

Component Structure

src/
├── components/
│   ├── ui/ (shadcn components)
│   ├── bets/ (domain-specific components)
│   └── [shared components]
├── contexts/ (React contexts)
├── hooks/ (custom hooks)
├── lib/ (utilities, Firebase config)
└── types/ (TypeScript definitions)

Coding Standards

TypeScript

• Always use proper typing, avoid any
• Use interfaces for complex objects
• Export types from src/types/index.ts
• Use optional chaining and nullish coalescing

React Patterns

• Use functional components with hooks
• Prefer useEffect with proper dependencies
• Use useState for local state, Context for shared state
• Always cleanup event listeners and timers

Performance

• Use useCallback and useMemo for expensive operations
• Lazy load components when appropriate
• Optimize images with Next.js Image component
• Minimize re-renders with proper dependency arrays

Accessibility

• Always include proper ARIA labels
• Use semantic HTML elements
• Ensure keyboard navigation works
• Maintain color contrast ratios
• Support screen readers

Context-Aware Theming

Baby Born State Detection

const babyBorn =
  appSettings?.actualBirthDate && appSettings.actualBirthDate.seconds;

Dynamic Styling Pattern

className={`base-styles ${
  babyBorn
    ? 'pink-celebration-styles'
    : 'indigo-waiting-styles'
}`}

Common Theme Patterns

• Borders: border-pink-200 dark:border-pink-800 vs border-indigo-200 dark:border-indigo-800
• Backgrounds: bg-pink-50 dark:bg-pink-950/30 vs bg-indigo-50 dark:bg-indigo-950/30
• Text: text-pink-700 dark:text-pink-300 vs text-indigo-700 dark:text-indigo-300

Development Guidelines

When Adding New Features

1. Start with mobile-first responsive design
2. Implement both normal and celebration mode styling
3. Add proper TypeScript types
4. Include accessibility features
5. Test with keyboard navigation
6. Verify color contrast in both light/dark modes

When Modifying Existing Components

1. Maintain existing responsive patterns
2. Keep context-aware theming consistent
3. Don't break mobile menu functionality
4. Preserve animation and transition consistency
5. Update documentation if patterns change

Code Quality

• Follow existing naming conventions
• Use descriptive variable and function names
• Add comments for complex logic
• Keep components focused and single-purpose
• Extract reusable logic into custom hooks

Testing Checklist

Responsive Testing

• Mobile (320px-640px)
• Tablet (640px-1024px)
• Desktop (1024px+)
• Both portrait and landscape orientations

Theme Testing

• Light mode (normal state)
• Dark mode (normal state)
• Light mode (celebration state)
• Dark mode (celebration state)

Accessibility Testing

• Keyboard navigation
• Screen reader compatibility
• Color contrast validation
• Motion preference respect

Browser Testing

• Chrome/Edge (primary)
• Safari (secondary)
• Firefox (secondary)
• Mobile browsers

Remember: This application celebrates a special moment, so the user experience should feel joyful, smooth, and professional. Every interaction should contribute to the celebratory atmosphere while maintaining usability and accessibility.