1---2name: timeline3description: Use when the user needs to communicate events or milestones in chronological order, with dates, intervals, eras, or parallel tracks.4---56# Timeline78## What and why910A timeline tells a chronological story: what happened, when it happened, and sometimes how parallel strands relate. It is useful for releases, incidents, historical context, migrations, and roadmaps.1112Choose it when time is the primary organizing axis. Avoid it for task scheduling with dependencies (gantt-chart), causal process flow (flowchart), or a person’s step-by-step experience (user-journey-map).1314## How15161. Choose the time scale and state it: dates, quarters, years, eras, or relative time.172. Select only events that advance the story; give each an unambiguous date or interval.183. Use a single track for one narrative and parallel tracks for independent streams. Keep labels short and put detail in notes.194. Distinguish event, milestone, interval, and uncertainty. Do not imply precision the source does not support.205. If the timeline is a roadmap, label commitment status separately from chronology.2122## Story and styling2324Use a strong axis and consistent date formatting. Encode event categories with shape or small color accents, but also label them for color-independent reading. Use whitespace for eras and avoid crossing annotations. For dense timelines, split into views by track or period.2526If no renderer is specified, use `mermaid` for its timeline syntax or `d2`/`graphviz` when custom layout is more important. These renderers do not provide a universal temporal data model; validate dates and uncertainty in the source data. Preserve an explicit renderer choice.2728## Review2930- Is the time scale and direction explicit?31- Are dates, intervals, and uncertain dates represented honestly?32- Can a reader distinguish tracks and event categories without color alone?33- Does every item earn its space in the narrative?34- Are roadmap status and chronological position kept separate?3536## Prior art and limitations3738For milestone and project communication, align terminology with [ISO 21502:2020](https://www.iso.org/standard/74947.html), while recognizing that a timeline is a communication view rather than a project-control model. For historical chronology, use the source domain’s date conventions and cite the source data.3940The supported text renderers do not guarantee date-aware scaling, collision avoidance, or semantic uncertainty encoding. A standards-aware timeline data model and date-scale renderer would be a useful integration opportunity.