Browser Pomodoro Timer

Project roadmap

1. 01

   Build the page

   ~1h

   Create index.html, style.css and app.js. Lay out a large mm:ss display, the current phase (Work, Short break or Long break), a session counter, and Start, Pause and Reset buttons. Make it look good on phones and give each phase its own color. Done when: the page shows the layout, and the buttons respond to clicks (logging to the console for now).

2. 02

   Count down accurately

   ~1.5h

   When Start is pressed, save the end time (Date.now() plus the duration), and every 250 ms compute the remaining time from the end time and update the display and the page title. Pause saves the remaining time; resume sets a new end time. Using the clock instead of counting ticks keeps it accurate even when the browser slows timers in background tabs. Done when: the timer counts down correctly, pauses and resumes.

3. 03

   Switch between work and breaks

   ~1h

   When the time reaches zero, record the session if it was work, then move to the next phase: a short break, or a long break after every 4th work session. Add a setting for whether the next phase starts automatically. Add a Skip button. Done when: the timer cycles through work and breaks in the right order.

4. 04

   Play a sound

   ~1h

   Create an AudioContext on the first click (browsers only allow sound after the user interacts), and play a short chime when a phase ends using an OscillatorNode and a GainNode that fades out. Add a mute toggle. Done when: a chime plays at the end of each phase, and muting stops it.

5. 05

   Save the history

   ~1h

   Save completed work sessions (with their end time) and the settings in localStorage as JSON, and show today's number of sessions and total focus time. Restore a running timer after reloading from its saved end time. Handle missing or broken saved data by starting fresh. Done when: the history and a running timer survive reloading the page.

6. 06

   Test it

   ~1h

   Put the timing logic (remaining time, next phase and today's totals) in functions that don't touch the page, and test them with a few assertions in a test page or with Vitest. Test by hand: a background tab, pausing, and reloading mid-session. Done when: the logic tests pass, and the manual checks work.

Resources

• DocsMDN: JavaScript first steps
• DocsMDN: introduction to the DOM
• DocsMDN: using the Web Audio API
• DocsMDN: Window.localStorage
• ArticlePomodoro Technique (Wikipedia)