kimai-plugin-heatmap/.planning/research/FEATURES.md

Feature Landscape

Domain: Time-tracking activity heatmap dashboard widget (Kimai plugin) Researched: 2026-04-08 Overall confidence: MEDIUM (based on training data knowledge of GitHub, GitLab, WakaTime, RescueTime, Toggl, and open-source heatmap libraries; no live verification available)

Reference Products Analyzed

Product	Heatmap Style	Key Insight
GitHub contribution graph	Year-long calendar grid, 5 color levels, tooltips	The gold standard UX -- simple, instantly understood, no configuration needed
GitLab activity calendar	Same layout as GitHub, slightly different color scheme	Proves the pattern is universal for developer audiences
WakaTime	Calendar heatmap + line charts + breakdowns by language/project	Heavier analytics layer on top of the basic heatmap
RescueTime	Daily productivity scores, category breakdowns, hour-of-day patterns	Focus on productivity categorization, not raw activity
Toggl Track insights	Weekly/monthly bar charts, project pie charts, calendar view	More report-centric than heatmap-centric
cal-heatmap (JS library)	Configurable calendar heatmap, multiple layouts	Popular open-source implementation, good API reference

Table Stakes

Features users expect from any calendar heatmap. Missing any of these makes the widget feel broken or incomplete.

Feature	Why Expected	Complexity	Notes
Calendar grid layout (weeks x days)	This IS the product -- the GitHub-style grid is the universally recognized pattern	Medium	d3.js renders SVG grid; each cell = one day
Color intensity mapping	Users expect darker = more activity, lighter = less; this is how every heatmap works	Low	4-5 discrete color levels (empty, low, medium, high, very high)
Tooltip on hover	Every reference product shows exact values on hover; without it users stare at colors guessing	Low	Show date, hours tracked, entry count
Sensible default time range	GitHub shows 1 year; users expect to see something useful without configuration	Low	Default to trailing 12 months
Day-of-week labels	Mon/Wed/Fri labels on the Y-axis for orientation	Low	Standard in GitHub/GitLab graphs
Month labels	Column headers showing month boundaries	Low	Standard in all calendar heatmaps
Empty state	Days with no entries should render as a distinct "no data" color, not be invisible	Low	Light gray or the theme's muted background color
Click-through to detail	Clicking a day should take you somewhere useful	Low	Navigate to Kimai timesheet view filtered to that date (already in PROJECT.md requirements)
Theme integration	Must not look like a foreign element glued onto the dashboard	Low	Use Kimai CSS variables for colors

Differentiators

Features that elevate the widget beyond a static pretty picture. Not expected by default, but each adds meaningful value for a personal time-tracking use case.

Feature	Value Proposition	Complexity	Notes
Toggle between hours and entry count	Different questions: "how much did I work?" vs "how consistently did I track?" -- GitHub only shows one metric	Low	Button or toggle in widget header; already in PROJECT.md requirements
Project/activity filter	Focus on one project at a time to see its cadence	Medium	Dropdown populated from Kimai data; re-renders heatmap on change
Configurable time range	See last 3 months, 6 months, full year, or custom range	Medium	Range selector in widget header; affects data query and grid size
Streak indicator	"Current streak: 12 days" -- gamification that motivates consistency	Low	Simple calculation: count consecutive non-zero days ending at today
Summary stats row	Total hours, average hours/day, busiest day -- quick numbers alongside the visual	Low	Small text row below or above the heatmap
Weekend vs weekday distinction	Subtle visual indicator (border, opacity) for weekends	Low	Helps distinguish work patterns from weekend work
Responsive widget sizing	Widget that adapts if Kimai dashboard column width changes	Medium	SVG viewBox scaling; cell size calculation based on container width

Anti-Features

Things to deliberately NOT build. Each would add complexity without serving the core "at a glance, see where your time went" purpose.

Anti-Feature	Why Avoid	What to Do Instead
Real-time updates / live refresh	Overengineered for a dashboard widget; page reload is fine for daily granularity data	Refresh data on page load only
Billable vs non-billable split	Out of scope per PROJECT.md; this is personal tracking, not client billing	Single aggregate view
Export/share heatmap as image	Out of scope per PROJECT.md; no audience to share with for personal use	Users can screenshot if needed
Hour-of-day heatmap (2D matrix)	Different visualization entirely; scope creep that doubles the frontend work	Stick to the calendar grid; could be a separate widget later
Drill-down charts within the widget	Clicking a day to show a pie chart of projects within the widget adds major complexity	Click-through to Kimai's existing timesheet/report views instead
Multi-user comparison	Personal tracking tool, not a team dashboard	Single-user view only
Goal setting / targets	Adds state management, settings UI, persistence -- a separate feature domain	Streak indicator covers the motivational angle simply
Animated transitions on data change	Cool but adds JS complexity for near-zero utility on a dashboard widget	Instant re-render on filter change
Mobile-specific layout	Out of scope per PROJECT.md; Kimai dashboard is a desktop experience	Standard responsive SVG is sufficient
Custom color theme picker	Theme integration with Kimai variables is sufficient; custom palettes add a settings UI nobody needs	Use Kimai theme variables, pick a single well-tested palette

Feature Dependencies

Calendar grid layout
  --> Color intensity mapping (needs the grid to color)
  --> Tooltip on hover (needs cells to attach to)
  --> Click-through to detail (needs cells to click)
  --> Empty state (needs grid cells for empty days)
  --> Day/Month labels (needs the grid structure)

Toggle hours/count
  --> Requires backend to return BOTH hours and count per day
  --> Re-maps color intensity without re-fetching data

Project/activity filter
  --> Requires backend filter parameter in data API
  --> Dropdown populated via separate Kimai API call (projects list)
  --> Triggers data re-fetch + full heatmap re-render

Configurable time range
  --> Requires backend date range parameter in data API
  --> Affects grid dimensions (fewer weeks = smaller grid)
  --> Triggers data re-fetch + full heatmap re-render

Streak indicator
  --> Depends on the same daily aggregation data as the heatmap
  --> No additional backend work if heatmap data is already loaded

Summary stats
  --> Depends on the same daily aggregation data as the heatmap
  --> Pure frontend calculation from existing data

MVP Recommendation

Phase 1 -- Core heatmap (all table stakes):

1. Calendar grid with color intensity (the product itself)
2. Tooltips on hover
3. Day/month labels and empty state
4. Click-through to Kimai timesheet view
5. Kimai theme integration

Phase 2 -- Interactivity (high-value differentiators):

1. Toggle between hours and entry count
2. Project/activity filter dropdown
3. Configurable time range

Phase 3 -- Polish (low-effort differentiators):

1. Streak indicator
2. Summary stats row
3. Weekend distinction

Defer indefinitely:

• Hour-of-day matrix, export, goals, animations, multi-user -- all anti-features for this context.

Rationale: Phase 1 delivers a complete, useful widget. Phase 2 adds the interactivity that makes it genuinely better than just looking at Kimai's existing reports. Phase 3 is cheap polish that improves daily experience but isn't blocking.

Sources

• GitHub contribution graph: well-known UX pattern (5 color levels, year grid, tooltips, contribution count)
• GitLab activity calendar: same pattern, confirms universality
• WakaTime dashboard: adds analytics layer (coding time heatmap, project breakdowns, streak tracking)
• RescueTime: productivity scoring approach, hour-of-day patterns
• Toggl Track insights: report-centric visualizations, project breakdowns
• cal-heatmap.com: popular open-source JS calendar heatmap library, API design reference
• All sourced from training data (no live verification available) -- MEDIUM confidence