Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Latest release: Component Library v56.16.1 (Oct 5, 2026)

Patterns

Dates and times - Design decisions

Key design decisions for the Dates and times pattern.

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Display timestamps in the Veteran’s local time zone instead of UTC

  • Decision date: June 1, 2026

Context

VA form submissions and API payloads store timestamps in UTC, but VADS lacked explicit guidance on how those timestamps should be displayed to Veterans in form UI and on generated PDFs. Without this guidance, individual form teams made inconsistent decisions about time zone context, leading to accessibility, localization, and usability inconsistencies across VA.gov forms. Displaying raw UTC or machine-formatted timestamps (for example, 2026-05-26T14:32:07Z) is not meaningful to Veterans and does not reflect the time they actually experienced.

Decision

Display timestamps to Veterans in a human-readable format using the Veteran’s local time zone, detected from their browser or device (for example, May 26, 2026, at 2:32 p.m. PT), rather than UTC or a fixed Eastern Time (ET). This applies everywhere a date or timestamp is shown back to a Veteran, including confirmation pages, review steps, saved-work alerts, and PDF timestamps (the watermark and VA DATE STAMP box). If the Veteran’s local time zone can’t be detected, use ET. Use standard, 2-letter time zone abbreviations (PT, CT, MT, ET) rather than the 3-letter abbreviations (EST, EDT). This guidance covers display only—timestamps must still be stored and transmitted in UTC ISO 8601 format, and converted to the Veteran’s local time zone at the point of display.

Consequences

Positive:

  • Veterans see timestamps in a format and time zone that’s meaningful to them, improving clarity and trust.
  • Consistent time zone display logic across confirmation pages, saved-work alerts, and generated PDFs reduces inconsistency between form teams.
  • Backend storage and transmission standards (UTC ISO 8601) are unaffected, so this decision doesn’t require changes to data pipelines.

Negative/watch items:

  • Existing PDF generation code and content that hardcoded UTC (or ET) timestamps needs to be updated to convert to the Veteran’s local time zone at render time. See Signature — Generating a PDF for implementation details.
  • Time zone detection can fail or be inaccurate (for example, VPNs or misconfigured devices). teams must implement the ET fallback correctly and test it.
  • Automated tests and snapshots that assert on UTC-formatted timestamps will need to be updated.
Edit this page in GitHub (Permissions required)
Last updated: Sep 29, 2026