🍅 Pomodoro Timer

A professional, accessible, and feature-rich Pomodoro timer built with vanilla JavaScript. Boost your productivity with the proven Pomodoro Technique.

✨ Features

Core Functionality

• ⏱️ Customizable Timers - Set your own work, break, and long break durations
• 🔄 Cycle Tracking - Zero-indexed cycles (0/4 → 4/4) with automatic long breaks
• 🎵 Background Music - YouTube integration with hidden player (audio only)
• 🔔 Smart Notifications - Browser notifications when sessions complete
• 💾 Auto-Save - All settings and progress saved automatically
• 📱 Progressive Web App - Install on any device, works offline

Professional Polish

• ♿ WCAG AA Compliant - Fully accessible to all users
• 🎨 Modern UI - Clean blue accent design with smooth animations
• 🌓 Dark Mode - Automatic dark mode based on system preferences
• ⌨️ Keyboard Shortcuts - Full keyboard navigation (Space, R, S)
• 📐 Responsive - Works perfectly on all screen sizes (360px to 4K)
• 🛡️ Offline Support - Service worker caches everything

Technical Excellence

• 🚀 Zero Dependencies - Pure vanilla JavaScript
• 🔧 Modular Architecture - Clean, maintainable code structure
• 🛡️ Error Handling - Comprehensive error handling and recovery
• 🔒 Privacy First - All data stored locally, no tracking
• 🌐 Cross-Browser - Works on Chrome, Firefox, Safari, Edge
• 📊 Professional Logging - Developer-friendly console messages

🚀 Quick Start

Installation

1. Clone the repository

   git clone https://github.com/hjadmz/pomodoro-timer.git
   cd pomodoro-timer
   

2. Serve the files

   Using Python:

   python -m http.server 8000
   

   Using Node.js:

   npx serve
   

   Using PHP:

   php -S localhost:8000
   

3. Open in browser

   http://localhost:8000
   

Usage

Basic Operation

1. Click Start to begin a 25-minute work session
2. Work until the timer completes
3. Take a 5-minute short break
4. After 4 work cycles, enjoy a 15-minute long break

Keyboard Shortcuts

• Space - Start/Pause timer
• R - Reset timer
• S - Jump to settings

Customization

1. Scroll to the Settings section
2. Adjust durations and cycles to your preference
3. Enable notifications (requires browser permission)
4. Add a YouTube URL for background music (optional)
5. Click Save Settings

📋 Browser Compatibility

Browser	Minimum Version	Support Level
Chrome	90+	✅ Full
Firefox	88+	✅ Full
Safari	14+	✅ Full
Edge	90+	✅ Full
iOS Safari	14+	⚠️ No notifications
Android Chrome	90+	✅ Full

🏗️ File Structure

pomodoro-timer/
├── index.html              # Main HTML
├── manifest.webmanifest    # PWA manifest
├── service-worker.js       # Offline support
├── offline.html           # Offline fallback
├── robots.txt             # SEO configuration
├── LICENSE                # MIT License
├── README.md              # This file
├── .gitignore             # Git exclusions
├── css/
│   └── style.css          # Complete stylesheet
├── js/
│   ├── state.js           # State management
│   ├── timer.js           # Timer logic
│   ├── player.js          # YouTube integration
│   ├── notifications.js   # Notification handling
│   ├── ui.js              # UI updates
│   └── app.js             # Main orchestrator
└── assets/
    └── icons/             # PWA icons (12 sizes)

🎨 Customization

Colors

Edit CSS custom properties in css/style.css:

:root {
  --color-primary: #3b82f6;        /* Blue accent */
  --color-success: #10b981;        /* Success states */
  --color-bg: #f8fafc;             /* Background */
  --color-text: #1e293b;           /* Text color */
}

Durations

Default durations in js/state.js:

const DEFAULT_STATE = {
  settings: {
    workDuration: 25,              // Minutes
    breakDuration: 5,              // Minutes
    longBreakDuration: 15,         // Minutes
    cyclesBeforeLongBreak: 4       // Cycles (0-indexed)
  }
};

♿ Accessibility Features

• Semantic HTML - Proper heading hierarchy and landmarks
• ARIA Labels - Comprehensive screen reader support
• Keyboard Navigation - All functionality accessible via keyboard
• Focus Indicators - Clear visual focus states
• Color Contrast - WCAG AA compliant (4.5:1+ ratios)
• Reduced Motion - Respects prefers-reduced-motion
• Touch Targets - Minimum 44x44px tap targets

🔒 Privacy & Security

• No Tracking - Zero analytics or tracking scripts
• Local Storage Only - All data stored on your device
• No External Requests - Except YouTube (optional)
• No Cookies - No cookies used
• Open Source - Full transparency

📱 Progressive Web App

Installation

Desktop:

1. Click the install icon in the address bar
2. Follow browser prompts

Mobile:

1. Open in browser
2. Tap "Add to Home Screen"
3. Confirm installation

Offline Support

• Works completely offline after first load
• Settings and progress saved locally
• Graceful degradation for online-only features

🐛 Troubleshooting

Notifications Not Working

1. Check browser supports notifications
2. Grant permission when prompted
3. Note: iOS Safari doesn't support web notifications

YouTube Player Not Loading

1. Check internet connection
2. Verify valid YouTube URL format
3. Check browser console for errors

Settings Not Saving

1. Ensure localStorage is available
2. Not in private/incognito mode
3. Check browser console for errors

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Standards

• Indentation: 2 spaces
• Naming: camelCase (JS), kebab-case (CSS)
• Comments: JSDoc for functions
• No emojis in code (only in README)

📄 License

This project is licensed under the MIT License - see LICENSE file.

👤 Author

Henry Adams

• GitHub: @hjadmz

🙏 Acknowledgments

• Pomodoro Technique® by Francesco Cirillo
• YouTube IFrame API by Google
• Inspired by the productivity community

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ by Henry Adams

Pomodoro Technique® is a registered trademark of Francesco Cirillo