Skip to content

🍅 Pomodoro Focus Timer

URL: aguidetocloud.com/pomodoro/
Status: ✅ Built, not yet integrated into site nav/toolkit
Accent: #EF4444 (Tomato Red)
Cost: $0/month — 100% client-side
Pipeline: None (browser JS + static WAV files)

Overview

A beautiful Pomodoro productivity timer with customisable focus sessions, ambient sounds, task tracking, and detailed statistics. Everything runs in the browser — no accounts, no API calls, all data stays in localStorage.

Architecture

Files

File Size Purpose
content/pomodoro/_index.md 3KB Front matter + 8 FAQ items
layouts/pomodoro/list.html ~14KB Hugo template — timer card, tabs, settings modal, JSON-LD
static/css/pomodoro.css ~14KB Full dark theme, glassmorphism, fullscreen mode
static/js/pomodoro.js ~42KB Timer core, tasks, settings, stats, ambient sound engine
static/audio/pomo-*.wav ~714KB 6 pre-generated ambient WAV loops (for future realistic sounds)
scripts/gen-ambient.py ~12KB Python/scipy script to regenerate WAV files

CSS Namespace

All classes use .pomo-* prefix. Body class: page-pomodoro.

Data Storage (localStorage)

Key Contents
pomo_settings JSON — all timer/sound preferences
pomo_tasks JSON array — task list with estimated/actual pomodoros
pomo_current_task Task ID string
pomo_stats JSON object — keyed by date YYYY-MM-DD, each has focusMin, sessions, tasksDone

Layout Design

The page uses a single-page timer approach — no tab switching needed for core features:

[Tool Hero — shared partial, Tomato Red accent]

[Timer Card — glassmorphism, always visible]
  ├── Duration presets: 25/5 | 50/10 | 90/15 | ⚙️ Custom
  ├── Phase label: FOCUS / SHORT BREAK / LONG BREAK
  ├── SVG ring timer (260×260, animated stroke-dashoffset)
  ├── Session dots (🍅 ● ● ○)
  ├── Controls: ↺ Reset | ▶ Start | ⏭ Skip
  ├── Quick task input (inline, click to expand)
  ├── Ambient sound pills (6 synthetic: Focus/Calm/Bright/Deep/Static/Warm)
  ├── Volume slider
  ├── Bottom row: 🍅 count | Auto toggle | Mute | Fullscreen | ⚙️ Settings
  ├── Break quote (hidden during focus)
  └── Keyboard shortcuts hint (desktop only)

[Two Tabs below timer card]
  ├── 📝 Tasks — full task list management
  └── 📊 Stats — today/week/all-time/heatmap

[Settings Modal — opens via ⚙️ button]
  ├── Timer durations (4 sliders)
  ├── Automation toggles
  ├── Alert sound type + volume
  └── Reset to defaults

Features

Timer (always visible)

  • SVG ring countdown — stroke-dashoffset animation, phase-coloured (red/green/blue)
  • Duration presets — 25/5, 50/10, 90/15 quick-switch pills, plus ⚙️ Custom opens settings
  • Phase indicator — colour-coded uppercase label
  • Session dots — 🍅 for completed, ○ for remaining (count matches "long break every N" setting)
  • Auto-start toggle — continues automatically between focus/break
  • Fullscreen mode — hides nav/footer/tabs, centres timer
  • Browser tab title — updates to 25:00 - Focus | Pomodoro
  • Browser notifications — when timer ends (requires permission)
  • Break quotes — 20 motivational quotes shown during breaks

Ambient Sounds (6 synthetic)

Uses Web Audio API — no external files needed:

Sound Colour Technique
Focus #EF4444 red Pink noise, mid-bandpass (warm, focused hum)
Calm #34D399 green Brown noise, lowpass + slow LFO (soothing deep drone)
Bright #FBBF24 gold White noise, highpass 3kHz+ (sparkly, airy)
Deep #3B82F6 blue Brown noise, lowpass 150Hz + volume swell (rumbling depth)
Static #A78BFA purple Clean white noise (simple, electronic)
Warm #F97316 orange Muffled brown noise + Cmaj7 chord tones (tonal, cozy)

Each pill has colour-matched border, background tint, hover glow, and pulsing active animation using CSS color-mix() + --pill-color custom property.

Future: Pre-generated WAV files exist in static/audio/ for realistic ambient sounds (rain, café, forest, ocean). The JS has startRealAmbient() ready to use them — just needs UI pills to be re-added.

Tasks

  • Add with Enter, set estimated pomodoros
  • Click to set as current focus (shown on timer)
  • Drag-to-reorder (mobile: ▲/▼ buttons)
  • Mark complete (✓), delete, clear completed
  • Track actual vs estimated pomodoros per task

Settings (modal)

  • Work duration: 1–90 min (default 25)
  • Short break: 1–30 min (default 5)
  • Long break: 1–60 min (default 15)
  • Long break interval: 2–8 sessions (default 4)
  • Auto-start breaks/focus toggles
  • Browser notifications toggle + test button
  • Alert sound: Chime, Bell, Digital, None
  • Alert volume + preview

Stats

  • Today: Focus minutes, sessions, tasks done, day streak
  • This Week: Bar chart (Mon–Sun, Canvas-rendered, today highlighted red)
  • All Time: Total hours, total sessions, longest streak, avg daily focus
  • Heatmap: GitHub-style 365-day grid, 5 intensity levels
  • Export CSV — date/focusMin/sessions/tasksDone
  • Clear all data — with confirmation

Keyboard Shortcuts

Key Action
Space Start/Pause
R Reset
S Skip phase
F Fullscreen toggle
M Mute toggle
Escape Exit fullscreen / close settings

SEO

  • WebApplication + FAQPage JSON-LD schema
  • 8 FAQ items (visible + structured data)
  • Pagefind searchable hidden block

Alert Sounds (Web Audio API)

All synthesised — no audio files:

Type Technique
🔔 Chime 3 ascending sine tones (C5, E5, G5), 180ms apart, exponential decay
🛎️ Bell 4 harmonics (A4 + octaves), long 3s decay
📟 Digital 3 short square wave beeps at 880Hz
🔇 None Silent

Pre-Generated WAV Files (for future use)

Script: scripts/gen-ambient.py — requires Python 3 + numpy + scipy.

cd C:\ssClawy\aguidetocloud-revamp
python scripts/gen-ambient.py

Generates 6 WAV files in static/audio/:

File Duration Size Technique
pomo-rain.wav 2.9s 89KB Pink noise + resonant drop impulses + intensity LFO
pomo-cafe.wav 3.8s 119KB Formant-filtered noise + metallic clink impulses + espresso burst
pomo-forest.wav 4.8s 148KB Subtle wind + bird chirps (3 types) + AM cricket tones
pomo-ocean.wav 5.7s 178KB Brown noise + asymmetric wave envelope + foam spray
pomo-whitenoise.wav 1.9s 61KB Clean white noise
pomo-lofi.wav 3.8s 119KB Lowpass Cmaj7 chord + vinyl crackle + bass pulse

All are mono 16kHz 16-bit, crossfade-looped for seamless playback.

Integration Status

Item Status
Content + template + CSS + JS ✅ Created
Tool hero (shared partial) ✅ Uses tool-hero.html
Body class in baseof.html ❌ Not added (page-pomodoro — needs one line)
toolkit_nav.toml ❌ Not added
Free tools page ❌ Not added
Homepage card ❌ Not added
Nav dropdown ❌ Not added
tool_count bump ❌ Not done
cache_version bump ❌ Not done
Smoke test coverage ❌ Not added
Git commit ❌ Not committed

Maintenance

  • No pipeline — fully static, no data to refresh
  • Settings/stats in localStorage — clearing browser data resets everything
  • Sound quality — synthetic sounds are abstract/labelled honestly. Realistic WAV files parked for future improvement (would need better source audio or ML-based generation)

Design Decisions

  1. Single-page timer — tasks + ambient sounds visible without switching tabs. Users who just want a timer get everything on one screen.
  2. Settings in modal — keeps the timer page clean. Power users find ⚙️, casual users get smart defaults.
  3. Synthetic sound labels — "Focus", "Calm", "Bright" etc. instead of pretending to be rain/forest. Honest naming for what they are.
  4. Duration presets — 25/5, 50/10, 90/15 covers most use cases without opening settings.
  5. Colourful ambient pills — each sound has its own colour for visual distinction. Uses CSS color-mix() for tinted backgrounds/borders from a single --pill-color variable.