How a calendar heatmap encodes data
A calendar heatmap maps one value per day onto a grid of small squares, with seven rows for the days of the week and up to 53 columns for the weeks of the year. Each square is shaded along a single colour ramp: an empty or near-white cell marks a day with no activity, and the most saturated cell marks the highest recorded value. Because every day occupies a fixed position, the format turns a long sequence of daily numbers into a single dense picture.
The encoding is deliberately simple. Only colour intensity carries the value, so the reader compares shades rather than reading numbers. This makes the chart fast to scan but imprecise: it is built to reveal patterns, not exact figures, which is why most implementations show the precise value on hover.
What patterns it reveals
Three structures stand out at a glance. Weekly cycles appear as horizontal banding, for example a clear gap on Saturday and Sunday rows for a work-driven metric. Seasonal trends appear as the grid darkening or lightening left to right across the year. Isolated spikes appear as single dark cells against a pale field, flagging an unusual day worth investigating.
Common uses
The format was popularised by the GitHub contributions graph and is now widely used for activity logging: code commits, daily step counts, training volume, website publishing cadence, and support ticket load. It also suits operational monitoring such as server error rates or daily sales, anywhere a year of one-value-per-day data benefits from a compact, at-a-glance view.