Stop Making Users Do Time Math: Relative Time Display for Vibe Projects

What does "2026-11-06T02:53:33.198Z" mean? A fictional lesson first

Here is a fictional teaching example. Lin Xiaoyu, a solo developer, used AI to build a recipe-sharing app called "Cloud Recipes", where users post recipes, comment, and like. In the first week after launch, she received a piece of feedback: "Is the comment timestamp broken? Every comment shows a string of numbers I cannot read." She opened it and saw that every comment timestamp looked like this: 2026-11-06T02:53:33.198Z. She stared at it herself — that was a raw ISO time string straight from the database, rendered directly on the page. What users actually wanted to know was simple: was this comment posted just now, or yesterday? What the page gave them instead was a code that first required converting time zones and then doing mental arithmetic against the current time.

That is the most common way time display dies: the time is not wrong, it is shown in the machine's language to a human. People look at time for only two reasons: how far away it is from now, and exactly when it happened. The first need calls for relative time — "3 minutes ago", "yesterday". The second calls for absolute time — "Nov 5, 14:30". Both are legitimate, but they belong in different places. Mix them up or use them in the wrong place and users have to do the conversion in their heads — and once the conversion goes wrong, trust goes with it: users think an order placed just now is three days old, or that yesterday's comment is a month old.

This guide covers how to do relative time display properly in a vibe project: when to use relative time and when absolute time is mandatory, a threshold table you can copy directly, the iron rule that the server stores only UTC timestamps, how the frontend renders and refreshes, and the edge cases — multiple languages, daylight saving time, and accessibility. All examples are fictional teaching examples; app names, personal names and numbers are simplified versions made up for illustration.

1. Relative time answers "how far from now", not "at what time"

Get the division of labor straight first, or even a perfect threshold table will be used in the wrong place. Relative time answers "how far from now": 3 minutes ago, 2 hours ago, yesterday, last week. Its biggest advantage is speed of reading: users can tell at a glance whether a comment is fresh or an order was just placed, without checking the clock, converting time zones, and doing mental math. Comment lists, feeds, notifications, and chat history — places ordered by time where newer matters more — are relative time's home turf.

Absolute time answers "at what time": Nov 5, 14:30, or Nov 5, 2026. Its biggest advantage is precision and verifiability: when something goes wrong and you need to investigate, reconcile accounts, or use a record as evidence, absolute time is what you rely on. Order details, invoices, payment records, logs, and anything legally relevant must use absolute time, with the time zone included. Imagine a user trying to reconcile an order with support while holding only "ordered 3 days ago" — support cannot pin down which order that is. Relative time is useless at that moment.

So rule one is: relative time in lists, absolute time in details — or show both. A comment list shows "3 minutes ago", and hovering over it reveals the full absolute time, "Nov 6, 2026, 10:53". That is the most common combination: fast to scan, precise when needed. Phones have no hover, so tapping the time can toggle the display, or the detail page can simply show absolute time. Do not offer only one, and do not cram both into the list — writing "3 minutes ago (2026-11-06 10:53)" on every row makes each row longer and kills the scanning advantage.

There is one more category where neither applies: countdowns and deadlines. "2 hours left until the event ends" is not relative time — that is a countdown, and it has its own approach. "Registration closes Nov 10, 23:59" must be written as absolute time with a time zone; writing "closes in 3 days" invites users to miscount the day. Relative time only covers "how far away something that already happened is". Future events and deadlines belong to countdowns and absolute time.

2. A threshold table you can copy: from "just now" to "last year"

The core of relative time is a threshold table: whichever interval the time difference falls into decides the label. There is no single global standard for the thresholds, but the table below is a default validated by many products — take it as is, and change only the numbers, never the structure.

Time difference	Chinese	English
0–10 seconds	刚刚	just now
10–60 seconds	几秒前	a few seconds ago
1–59 minutes	X 分钟前	X minutes ago
1–23 hours	X 小时前	X hours ago
Yesterday (calendar day)	昨天	yesterday
Day before yesterday (calendar day)	前天	the day before yesterday
3–6 days ago	X 天前	X days ago
1–4 weeks ago	X 周前	X weeks ago
1–11 months ago	X 个月前	X months ago
Over 1 year	X 年前，or the full date	X years ago, or the full date

Three details in the threshold table are the easiest to get wrong. The first is that "yesterday" must be measured in calendar days, not 24 hours. A comment posted at 11 p.m. yesterday, read at 1 a.m. today, is only 2 hours old — but in calendar days it is already "yesterday". The other way around, a comment from 3 p.m. the day before yesterday is 34 hours old; counting by 24-hour blocks would show "1 day ago", but by calendar days it should be "the day before yesterday". The fix is to convert both timestamps to dates in the user's local time zone first, then subtract the dates: a difference of 0 days is today, 1 day is yesterday, 2 days is the day before yesterday. Put the date-difference logic in a shared utility function — never reimplement it on every page.

The second is flicker at the boundaries. At 59 seconds the label says "a few seconds ago", at 61 seconds it says "1 minute ago", and near the boundary every refresh flips the label, making time look glitchy. The fix is to add a little tolerance at the boundary: show "1 minute ago" anywhere from 59 to 90 seconds, or stretch the refresh interval so the label stays stable in one bucket for a while before changing. An even simpler option: show "just now" for everything under 60 seconds, and erase the jitteriest bucket entirely.

The third is that beyond one year, stop being relative. "3 years ago" carries almost no information — a comment from 2023 and one from 2024 look equally old in a list, and users cannot tell them apart. Beyond one year, show the absolute date, "Mar 12, 2024", and users can place it instantly. Many products get lazy here and stay relative all the way down, with the result that a three-year-old post and a three-month-old post look about equally fresh.

Future times need a rule too. Server time and device time always differ by a few seconds or minutes, so a comment posted a moment ago can compute to a negative difference — "5 seconds in the future". When that happens, do not show "-5 seconds ago" or "in 5 seconds". Show "just now" for all of it. Genuine future times, like "the event starts in 3 minutes", are the countdown's job, not the relative-time table's.

3. The single source of truth: the server stores only UTC timestamps, the frontend renders in the user's time zone

There is one iron rule for time display: the server stores only UTC timestamps, and the frontend renders them in the user's time zone. It breaks into three statements, and none of them can be skipped.

First, store timestamps, not strings. Store a Unix timestamp like 1730875200 in the database, or a timestamptz type that carries its time zone. Never store a bare string like "2026-11-06 10:53" with no time zone, and never store a rendered result like "3 minutes ago". A timestamp is the one true fact; a string loses its time zone the moment it is saved and can never get it back; "3 minutes ago" is still "3 minutes ago" when the page is opened three days later — completely wrong.

Second, use UTC through the whole pipeline and convert to local time only at the last moment. The backend API returns timestamps, and the frontend renders them using the user's device time zone. Use the platform's internationalization APIs for that step — Intl.DateTimeFormat and Intl.RelativeTimeFormat in JavaScript — and let the browser handle it by the user's language and time zone. Hand-rolled time zone conversion will break on daylight saving day, and it will break silently.

Third, never trust the user's device clock. A phone's clock can be 5 minutes fast, 10 minutes slow, or stuck on last year. When relative time computes to "5 minutes in the future", do not try to correct the user's clock — just show "just now". For anything where precision matters, such as payments and orders, use a time supplied by the server as the baseline instead of taking new Date() from the device. Device time is for rendering only, never for decisions.

// Wrong: storing the rendered label in the database — it still says "3 minutes ago" three days later
await db.comments.insert({ text, createdLabel: '3 minutes ago' });

// Right: store only the UTC timestamp, compute the display at render time
await db.comments.insert({ text, createdAt: new Date().toISOString() });

// Rendering: use the platform API, never build the string by hand
const rtf = new Intl.RelativeTimeFormat('zh-CN', { numeric: 'auto' });
rtf.format(-3, 'minute'); // "3 分钟前"
rtf.format(-1, 'day');    // "昨天"
const dtf = new Intl.DateTimeFormat('zh-CN', { dateStyle: 'medium', timeStyle: 'short' });
dtf.format(new Date('2026-11-06T02:53:33.198Z')); // shown in the user's time zone

One more detail: when an API returns a time, return both the timestamp and the ISO string. The timestamp is for code to compute with; the ISO string is for humans debugging. Returning only one means an extra conversion step during debugging; returning a "local time string" loses the time zone again. Write this convention into the API docs and keep it consistent across the whole product.

4. Frontend rendering: how often to refresh, and only refresh what is visible

Relative time ages: "just now" becomes "1 minute ago" after a minute, and "1 hour ago" after an hour. So the frontend cannot render once and forget about it — it has to refresh on a timer. Refreshing has three concerns: the interval, the scope, and consistency.

Start with the interval. Refresh on a sliding scale by age: content under 60 seconds old refreshes every 10 seconds; under 1 hour, every 30 seconds; under 1 day, every 5 minutes; older than 1 day, once an hour is enough. The logic is simple: newer content changes faster, older content changes slower. Refreshing everything every 30 seconds also works, but with hundreds of timestamps in a list, a low-end phone will visibly stutter. With tiered refreshing, only the top few items on screen need the fast cadence.

Then the scope. Refresh only what the user can see. A page with a hundred comments shows only the first ten — refreshing the other ninety is wasted work. Use IntersectionObserver to find which time elements are in the viewport and refresh only those; pause the ones that scroll out of view and resume them when they come back. Chat windows work the same way: only the open conversation needs frequent refreshes; the conversation list in the background can refresh once an hour.

Finally, consistency — and server-side rendering is where it bites. Many projects use SSR: the server renders the HTML first and sends it to the browser. If the server computes "3 minutes ago" from server time and the browser recomputes it from device time after hydration, the two differ by a few seconds and the page flickers: "3 minutes ago" first, then "4 minutes ago" after hydration. The fix is to have the server render only the timestamp plus a placeholder, with the browser computing the relative time uniformly after takeover — or to make server and browser use the same threshold function and the same timestamp so both compute the same result. Either approach works, but the two sides must not compute independently.

One more easily missed point: when a page goes to the background, browsers throttle or stop its timers. When the user comes back, the time display may still show the version from half an hour ago. Listen for the visibilitychange event and refresh all timestamps immediately when the page becomes visible again. One line of code, and the time users see on return is always correct.

5. Multiple languages: the same table, different phrasing per language

Relative time gets messy the moment you add a second language, because languages express time differently. English has singular and plural — "1 minute ago" versus "2 minutes ago" — while Chinese has no such distinction. English has one word for "yesterday"; Chinese also has one word, but "the day before yesterday" has no single-word English equivalent, only a phrase. Arabic varies time expressions by gender. You cannot cover all of this with hand-written if-else branches.

The correct approach is to use a single API for the whole product — Intl.RelativeTimeFormat — and let the browser handle plurals, word forms, and word order. Pass 'zh-CN' and you get Chinese, 'en-US' and you get English, 'ja-JP' and you get Japanese, with no translation tables of your own to maintain. Turn on the numeric: 'auto' option: it renders -1 day as "yesterday" instead of "1 day ago", and -1 hour as "an hour ago", which reads like human speech. Turn it off and the English interface fills up with "1 day ago" — not wrong, but stiff.

Date formats must follow the language too. Chinese users expect "11 月 6 日", English users expect "Nov 6", German users expect "6. Nov." Use Intl.DateTimeFormat for absolute times as well and let the browser order the parts by language. The 12-hour versus 24-hour clock is the same story: Chinese and English default to 12-hour with AM/PM, German and French default to 24-hour. Never hard-code "HH:mm" or "h:mm a" — hard-coding one offends users of the other.

One more detail: the week starts on different days in different places. "Last week" in Chinese and English usually starts on Sunday or Monday, and the start day differs by region; in regions using the Islamic calendar the week starts on yet another day. For "X weeks ago" across languages, prefer "X days ago", or show the absolute date — avoid betting a cultural difference on the word "week". When days can say it clearly, do not gamble on "week".

6. Edge cases: daylight saving, New Year, and accessibility — none can be skipped

Almost every pitfall in time display lives in the edge cases. Start with daylight saving time. Twice a year the clocks change, making one day 23 hours and another 25 hours. Computing day differences by dividing milliseconds by 86,400,000 on those days counts the 23-hour day as 0 days and the 25-hour day as more than 1 day — so "yesterday" shows as "today" or the other way around. The fix is to always subtract local calendar dates, never divide milliseconds: convert both timestamps to year-month-day in the user's time zone first, then subtract the dates. Date subtraction is immune to daylight saving, because dates do not come in 23-hour and 25-hour versions.

Then the New Year. A comment from Dec 31, read on Jan 1, is only 1 day old — relative time correctly says "yesterday" — but the absolute time must carry the year: "Dec 31, 2025", not just "Dec 31", or users cannot tell which year's Dec 31 it is. The rule: absolute times within the current year may omit the year; last year's times must include it. Build that rule into the formatting function instead of leaving each page to decide for itself.

Then clock skew. As noted above, device clocks can be wrong, and a computed future time is shown as "just now". But server clocks can be wrong too: two servers a few minutes apart mean a comment written by server A reads as "3 minutes in the future" on server B. The real cure is time synchronization between servers — basic operations hygiene. The bandage is a rule in the relative-time function: any difference between -5 minutes and 0 displays as "just now". A future time beyond -5 minutes means something is genuinely wrong — log an alert instead of continuing to cover it up with "just now".

Finally, accessibility — the easiest one to forget. Relative time is unfriendly to screen readers: hearing "3 minutes ago" is fine, but users who want the exact time have no way to get it. Wrap every relative time in HTML's time element, put the full ISO timestamp in the datetime attribute, and show the relative time as the element's content: <time datetime="2026-11-06T02:53:33.198Z">3 minutes ago</time>. Screen readers get the exact time, and hovering shows the absolute time. Do not forget users with color blindness either: never use color alone to distinguish "new" from "old" — orange for new and grey for old is invisible to them. New versus old must be distinguishable in the words themselves, with color only as a supplement.

7. The pre-launch test checklist

Before launch, run through these scenarios one by one. Do not ship after testing only that "3 minutes ago" displays.

The first group is threshold boundaries: time differences of 0 seconds, 10 seconds, 59 seconds, 61 seconds, 59 minutes, 61 minutes, 23 hours, and 25 hours — what does each show? Watch the 59-to-61-second and 59-to-61-minute boundaries for flicker, and check that content from 11 p.m. yesterday reads as "yesterday" at 1 a.m. today, not "2 hours ago".

The second group is time zones: switch the device time zone to Beijing, London, New York, and Sydney in turn. The absolute time for the same comment should differ in each, but the relative time should be identical. Then move the system clock 10 minutes forward and check that future times show "just now" instead of a negative number.

The third group is daylight saving: pick a switchover date, such as Mar 29, 2026 in Europe, and check that content from the day before the switch still computes to a 1-day difference — not 0 or 2. This group only needs to be run once when the threshold function is written, and written down.

The fourth group is language: switch the interface to English and check that "1 minute ago" and "2 minutes ago" get singular and plural right; switch to Chinese and check that "yesterday" and "the day before yesterday" follow calendar days; switch to Japanese and check for half-Chinese, half-English mixed output. Mixed output is the most common localization bug: one missing entry in the threshold table and a Chinese phrase suddenly appears in the English interface.

The fifth group is refreshing and performance: open a list of a hundred comments and check whether a low-end phone stutters; switch to the background for 10 minutes and come back to see whether the times refresh immediately; on a server-rendered page, check whether the time display flickers after hydration.

Run all five groups, then launch. In the first week after launch, watch two numbers: how many user reports mention "the time is wrong", and the click rate on the absolute-time hover. Many complaints mean the thresholds or time zones are wrong; a high hover click rate means users often need the exact time, so show absolute time in more places. Nobody will praise you for relative time done well — they only come to you when the time is wrong. The goal is for them to never need to.

8. Common anti-patterns: mistakes others have already made

Anti-pattern one: dumping the database value straight to users. Comments showing 2026-11-06T02:53:33.198Z, or a raw Unix timestamp like 1730875200. Machine language must never appear in the user interface — every timestamp passes through a formatting function before display.

Anti-pattern two: staying relative all the way down. A three-year-old post still saying "3 years ago", leaving users unable to tell which year it is from. Switch to absolute dates beyond one year — that is what the last row of the threshold table is for.

Anti-pattern three: a separate threshold implementation on every page. One for the list page, one for the detail page, one for notifications — then a threshold change gets applied in two places and missed in the third, and the same moment shows three different labels in three places. There can only be one threshold function in the whole product, in a shared utility module, called by every page.

Anti-pattern four: using device time for decisions. Order timeouts, coupon expiry, event deadlines — these must be judged by server time. Judging by device time hands the rules to the user: set the phone clock back an hour and the coupon "comes back to life". Device time renders the display only; all decisions use server time.

Relative time comes down to one sentence: do not make users calculate time. One glance tells them whether something was just posted or posted yesterday, and hovering shows the exact time when they need it. That is enough. Threshold table, UTC timestamps, timed refresh, multiple languages, accessibility — when every link in the chain is done properly, time display is genuinely "done", not merely "displaying".