Timeline

An ordered list of moments on a rail: a date, a title and as much text as each moment needs. It is an <ol> with a <time> per item, so the order and the dates are in the markup and not only in the drawing. State is written by the author in data-iv-state; the marker changes shape as well as colour. No JavaScript.

CSS: css/components/timeline.css (in ivolt.css). Added in v0.6.

Vertical railfixtures/timeline/basic.htmlOpen alone

<ol class="iv-timeline" style="max-width: 34rem">
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09">Phase 1–4</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Foundations shipped</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Tokens, layout, buttons, forms, dialog and the layer order, frozen in the contract.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09">v0.5</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Time &amp; light</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Datepicker, tooltip, popover, megamenu and the effects layer; gate green in three engines.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="current">
    <time class="iv-timeline__time" datetime="2026-09">v0.6</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Structure</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Expressive-layer tokens, navbar, stepper, declarative toast and these content blocks.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="upcoming">
    <time class="iv-timeline__time" datetime="2026-10">v0.7</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Planned, not written</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Animated counter and the remaining candidates of the roadmap. Nothing here is published yet.</p>
    </div>
  </li>
</ol>

<p class="iv-u-text-sm iv-u-text-muted iv-u-mt-6" style="max-width: 34rem">The states come from the real roadmap of this package (<code>docs/ROADMAP.md</code>): three moments done or in progress, one still planned. State is written by the author in <code>data-iv-state</code>; the marker shape carries it as well as the colour.</p>

Alternating sides

iv-timeline--alternate hangs the items from a central rail, alternating sides from the md breakpoint up; below it the list falls back to the single rail of the default. It wants short entries: a long paragraph on the left and a short one on the right makes a ragged column.

Alternating railfixtures/timeline/alternate.htmlOpen alone

<ol class="iv-timeline iv-timeline--alternate" style="max-width: 44rem">
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09-13">13 Sep 2026</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Contract frozen</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Classes, tokens, attributes and events named before a line of CSS.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09-14">14 Sep 2026</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Owner's visual review</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Twenty-two modules polished against real screenshots, baselines regenerated.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="current">
    <time class="iv-timeline__time" datetime="2026-09-14">Today</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">v0.6 in progress</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Shared tokens for shadow, halo and tracking; content blocks land with their fixtures.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="upcoming">
    <time class="iv-timeline__time" datetime="2026-10">Next</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Release review</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Nothing is published or deployed without explicit authorisation.</p>
    </div>
  </li>
</ol>

<p class="iv-u-text-sm iv-u-text-muted iv-u-mt-6">From the <code>md</code> breakpoint up the items hang from a central rail, alternating sides; below it the list falls back to the single rail of the basic timeline.</p>

Horizontal rail

iv-timeline--horizontal lays the items out in columns along a horizontal rail from md up, scrolling with snap points. A scroll region needs to be reachable from the keyboard, so the author serves tabindex="0" and a label on the list itself; the CSS gives it a focus ring.

Horizontal railfixtures/timeline/horizontal.htmlOpen alone

<ol class="iv-timeline iv-timeline--horizontal" tabindex="0" aria-label="Release history">
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09">v0.1</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Blueprint</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Bible, architecture and contract written first.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09">v0.3</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Spectacular</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Carousel, picker, surfaces and the expressive layer.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="done">
    <time class="iv-timeline__time" datetime="2026-09">v0.5</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Time &amp; light</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Datepicker, tooltip, popover, megamenu.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="current">
    <time class="iv-timeline__time" datetime="2026-09">v0.6</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Structure</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Navbar, stepper and content blocks.</p>
    </div>
  </li>
  <li class="iv-timeline__item" data-iv-state="upcoming">
    <time class="iv-timeline__time" datetime="2026-10">v0.7</time>
    <div class="iv-timeline__body">
      <h3 class="iv-timeline__title">Planned</h3>
      <p class="iv-u-m-0 iv-u-text-sm">Counter and the rest of the roadmap.</p>
    </div>
  </li>
</ol>

<p class="iv-u-text-sm iv-u-text-muted iv-u-mt-6">The horizontal rail scrolls with snapping. The author serves <code>tabindex="0"</code> and a label on the list so the scroll region is reachable from the keyboard.</p>

Anatomy

Class	Element	Role
`iv-timeline`	`<ol>`	The rail. Ordered, because a timeline has a direction.
`iv-timeline__item`	`<li>`	One moment; draws its segment of the line and its marker.
`iv-timeline__time`	`<time datetime>`	The date, in small caps mono. A machine-readable `datetime` makes it more than a label.
`iv-timeline__body`	`<div>`	Everything else: title, text, links.
`iv-timeline__title`	heading	Name of the moment; pick the level the page needs.
`iv-timeline--compact`	modifier	Tighter rhythm for a list of many short entries.

States

data-iv-state on an item takes done (filled marker), current (filled with the shared focus halo and a slow pulse) and upcoming (hollow marker and muted text). An item without the attribute is drawn like a done one. The pulse stops under prefers-reduced-motion, and in forced-colors mode the markers keep their outline so the three states stay apart without colour.

Tokens and locals

Local	Default	What it moves
`--iv-timeline-line`	`var(--iv-color-border)`	Colour of the rail.
`--iv-timeline-marker`	`var(--iv-color-primary)`	Colour of the markers.
`--iv-timeline-size`	`0.75rem`	Diameter of a marker.
`--iv-timeline-rail`	`1.25rem`	Distance from the rail to the text.
`--iv-timeline-gap`	`var(--iv-space-6)`	Space between items.
`--iv-timeline-top`	`0.2rem`	Vertical nudge that lines a marker up with the first line of its text.

The __time uses --iv-tracking-caps, one of the expressive-layer tokens added in v0.6 (see tokens and themes), so its small caps match table headers and fieldset legends.

Accessibility and keyboard

The list order is the chronology, so nothing depends on reading the rail. Every date is a <time> with a machine-readable value. State reaches the drawing through marker shape and text, never colour alone — if a state matters to a reader, say it in words in the body as well. The horizontal variant is a scroll region: serve it with tabindex="0" and an aria-label so it can be scrolled with the keyboard, as its fixture does.

Without JavaScript

There is no JavaScript. Nothing is initialised, nothing is registered, nothing changes after the page loads: the timeline is a list with a rail drawn by pseudo-elements.

Common mistakes

A <ul> instead of an <ol>. The order is the point.
A date as plain text. <time datetime="2026-09"> costs nothing and means something.
Marking the current moment with colour only. The marker shape and the copy should say it too.
Long paragraphs in the alternating variant: the two columns stop lining up and the rail loses its rhythm.

Every content component

Every interactive component

Navigate