Timeline

Usage

• Use Timeline when event order changes how someone understands the state of an object.
• Use it for delivery events, journey activity, status history, audits, and ordered state transitions.
• Do not use Timeline for unrelated facts, navigation, menus, or lists where sequence is incidental.
• Use TimelineItem for events. For explanatory context inside the sequence, use a marker-less TimelineItem (one with no markerContent, markerIcon, or markerIconSrc) hosting a Banner or other content; it renders no coin, runs full width, and the rail passes through it neutrally.

Appearance

• Color (color) should describe event meaning consistently: blue for informational delivery steps, green for completed or successful steps, yellow for caution or machine-attributed states, red for failed or critical states, purple for feature-specific states, and grey for neutral states.
• Marker size (markerSize) controls marker size. Use sm for compact title-only timelines and lg for framed activity rows or larger custom row content.
• The marker is a Coin. Set its contents with markerIcon (a Pluma icon), markerIconSrc (an image URL rendered inside the coin), or markerContent (text such as a step number, or any node — in Ember a markerContent block); the icon scales automatically with the marker size. Setting markerContent to an empty string renders an empty coin (a plain node on the rail). markerContent takes precedence over markerIcon/markerIconSrc. color sets the marker and rail accent; shape (circle or rounded-square) distinguishes marker categories. isCurrent rings the marker and follows its shape.
• Use trackColor to color the rail apart from the marker (set it alongside color, which colors both). Like color, the track color carries onto the next row's incoming rail half.
• Line variant (lineVariant) controls the rail segment through a row. Prefer solid; use dashed for expected or provisional continuity and dotted for explanatory or related notes. A row's line variant carries onto the next row's incoming half, so the connector between two events is dashed/dotted end to end.
• Do not invent custom line widths, marker sizes, or font styles. Use tokenized props first.

Behaviors

• Timeline renders as an ordered list by default. Items render as list items by default, including marker-less rows.
• Markers are decorative by default. Add markerLabel only when the marker communicates information not already present in visible text.
• Use isCurrent once per timeline when one event is the current or most important status.
• Leave color unset (it defaults to grey) for unavailable, inactive, or expected future events to de-emphasize them.
• Markers align to the first line of each row's content (the same with or without a title). The connecting line runs from each marker to the next, staying continuous regardless of row height.
• Meta sits in a leading column before the marker by default (suited to activity logs with a persistent date or timestamp column); use metaPosition="trailing" when the meta is secondary to the event content.

Content

• Write event titles as past-tense outcomes, such as Sent email, Machine opened, or Human clicked.
• Keep titles short enough to scan.
• Put timestamps, dates, counts, or short statuses in meta.
• Put longer explanation in description or a Banner inside a marker-less TimelineItem.
• Use marker-less rows sparingly to explain a rule, transition, or attribution change that affects nearby events.

Implementation Notes

• React invocation: <Timeline><TimelineItem color="blue" markerIcon="send-auto" title="Sent email" meta="10:04 AM" /></Timeline>.
• Ember invocation: <PlumaTimeline><PlumaTimelineItem @color="blue" @markerIcon="send-auto" @title="Sent email" @meta="10:04 AM" /></PlumaTimeline>.
• markerIcon values come from Pluma Icons. Use markerIconSrc to render an image URL inside the marker coin instead of an icon. The marker icon scales automatically with the chosen marker size.
• For Journey-style activity rows, use markerSize="lg" on each row, and custom row content inside each item (meta is leading by default).
• For delivery metric timelines, use per-row color, shape, lineVariant, and isCurrent to separate machine and human event states; leave color unset to de-emphasize pending states.