# Timeline

An ordered sequence of events with per-item state, connectors, titles, timestamps, and vertical or horizontal flow.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/status/Timeline/Timeline.tsx

## Guidance

{
  "summary": "An ordered sequence of events with per-item state, connectors, titles, timestamps, and vertical or horizontal flow.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "An ordered sequence of events or steps over time, connected by a line and driven by a per-item\n`state` (complete / active / upcoming)."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Timeline` when the stages themselves carry content — a removal journey, an activity log,\na multi-day process — and each event has a title, optional description, and timestamp worth showing.\n\n-   Only showing position in a short flow (\"step 2 of 4\") with no per-event detail? Use\n    `Progress.Steps`, the active stepper.\n-   An unordered set of rows with no temporal sequence or connector line? Use `List`."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/status/Timeline/Timeline.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "items",
      "type": "readonly TimelineItem[]",
      "declared_type": "readonly TimelineItem[]",
      "required": true,
      "description": "Events in render order; each `id` keys its row and seeds its test id.",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 33
      }
    },
    {
      "name": "ariaLabel",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Names the ordered list for assistive tech.",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 35
      }
    },
    {
      "name": "orientation",
      "type": "TimelineOrientation | undefined",
      "declared_type": "TimelineOrientation",
      "required": false,
      "description": "Direction used to lay out events. Defaults to `'vertical'`.",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 37
      },
      "values": [
        "horizontal",
        "vertical"
      ],
      "values_complete": true,
      "default": "'vertical'",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 38
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 39
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector. Each event derives `${testId}-${item.id}`.",
      "source": {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 41
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Timeline",
    "public_path": "Timeline",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Timeline",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
          "line": 48
        },
        "props_type": "TimelineProps",
        "props": [
          {
            "name": "items",
            "type": "readonly TimelineItem[]",
            "declared_type": "readonly TimelineItem[]",
            "required": true,
            "description": "Events in render order; each `id` keys its row and seeds its test id.",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 33
            }
          },
          {
            "name": "ariaLabel",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Names the ordered list for assistive tech.",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 35
            }
          },
          {
            "name": "orientation",
            "type": "TimelineOrientation | undefined",
            "declared_type": "TimelineOrientation",
            "required": false,
            "description": "Direction used to lay out events. Defaults to `'vertical'`.",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 37
            },
            "values": [
              "horizontal",
              "vertical"
            ],
            "values_complete": true,
            "default": "'vertical'",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 38
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 39
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector. Each event derives `${testId}-${item.id}`.",
            "source": {
              "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
              "line": 41
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 7,
        "name": "TimelineItemState",
        "code": "export type TimelineItemState = 'complete' | 'active' | 'upcoming';"
      },
      {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 8,
        "name": "TimelineOrientation",
        "code": "export type TimelineOrientation = 'vertical' | 'horizontal';"
      },
      {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 13,
        "name": "TimelineItem",
        "code": "export interface TimelineItem {\n    /** The React key for the event and the `${testId}-<id>` selector suffix, so it must be unique within the sequence. */\n    id: string;\n    /** Event name. Drops to body-small in the horizontal orientation. */\n    title: React.ReactNode;\n    /** Optional detail line beneath the title. */\n    description?: React.ReactNode;\n    /** Step-state axis shared with progress components. */\n    state: TimelineItemState;\n    /** Optional glyph for active or upcoming events. Complete events always show a check. */\n    icon?: React.ReactNode;\n    /** Optional time, shown opposite the title vertically and beneath it when horizontal. */\n    timestamp?: React.ReactNode;\n}"
      },
      {
        "path": "packages/design-system/src/components/status/Timeline/Timeline.tsx",
        "line": 31,
        "name": "TimelineProps",
        "code": "export interface TimelineProps {\n    /** Events in render order; each `id` keys its row and seeds its test id. */\n    items: readonly TimelineItem[];\n    /** Names the ordered list for assistive tech. */\n    ariaLabel?: string;\n    /** Direction used to lay out events. Defaults to `'vertical'`. */\n    orientation?: TimelineOrientation;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Optional test selector. Each event derives `${testId}-${item.id}`. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Timeline",
      "status": "preview",
      "version": "1.0.0",
      "summary": "An ordered sequence of events with per-item state, connectors, titles, timestamps, and vertical or horizontal flow."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "Ordered list that flows events vertically or horizontally.",
        "required": true
      },
      {
        "id": "item",
        "label": "Item",
        "description": "One event row pairing a marker column with content."
      },
      {
        "id": "node",
        "label": "Node",
        "description": "State marker showing a check, custom icon, or active dot."
      },
      {
        "id": "connector",
        "label": "Connector",
        "description": "Line joining adjacent events."
      },
      {
        "id": "content",
        "label": "Content",
        "description": "Title, timestamp, and optional description."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "events": {
          "label": "Events",
          "description": "The single ordered-event treatment."
        }
      },
      "sizes": {},
      "orientations": {
        "vertical": {
          "label": "Vertical",
          "description": "Events stack top to bottom."
        },
        "horizontal": {
          "label": "Horizontal",
          "description": "Events flow left to right and scroll on overflow."
        }
      }
    },
    "variants": [
      {
        "id": "events",
        "label": "Events",
        "description": "Ordered event sequence with connectors.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "item-gap",
        "label": "Marker and content gap",
        "kind": "exact",
        "token": "--cds-space-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "item"
        ]
      },
      {
        "id": "node-size",
        "label": "Node size",
        "kind": "exact",
        "token": "--cds-size-24",
        "value": 24,
        "unit": "px",
        "appliesTo": [
          "node"
        ]
      },
      {
        "id": "content-inset",
        "label": "Content bottom inset",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "content"
        ]
      }
    ],
    "layout": {
      "alignment": "The marker column aligns with the top of each event's content.",
      "flow": "Vertical stacks a node-plus-content grid per event; horizontal lays events in a scrolling row.",
      "notes": [
        "Use Progress.Steps when you only need position in a short flow without event detail."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Title",
          "description": "Uses the body ramp (body-small when horizontal).",
          "token": "--cds-type-body-size"
        },
        {
          "label": "Timestamp and description",
          "description": "Use the body-small ramp.",
          "token": "--cds-type-body-small-size"
        }
      ],
      "colors": [
        {
          "label": "Complete",
          "description": "Complete nodes and connectors use the brand accent.",
          "token": "--cds-brand"
        },
        {
          "label": "Active",
          "description": "Active nodes use the subtle brand wash.",
          "token": "--cds-brand-subtle"
        },
        {
          "label": "Upcoming",
          "description": "Upcoming nodes outline with the divider color.",
          "token": "--cds-divider"
        }
      ]
    },
    "states": [
      {
        "id": "complete",
        "label": "Complete",
        "description": "Finished event with a filled node and check."
      },
      {
        "id": "active",
        "label": "Active",
        "description": "Current event, marked aria-current=step."
      },
      {
        "id": "upcoming",
        "label": "Upcoming",
        "description": "Future event with an outlined node."
      }
    ],
    "behavior": [
      {
        "label": "Per-item state",
        "description": "Each event declares complete, active, or upcoming; the active event is aria-current."
      },
      {
        "label": "Connectors",
        "description": "A connector joins each event to the next; the last event omits it."
      }
    ],
    "accessibility": [
      {
        "label": "Ordered list",
        "description": "Renders as an ordered list; set ariaLabel to name the sequence."
      },
      {
        "label": "Current step",
        "description": "The active event exposes aria-current=step."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Optional detail",
        "description": "Description and timestamp render only when provided."
      },
      {
        "label": "Horizontal overflow",
        "description": "The horizontal layout scrolls when events exceed the width."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "Static",
          "description": "Timeline does not animate state transitions."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "Timeline is non-interactive and requests no haptics."
        }
      ]
    },
    "platformDifferences": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-size-24",
      "light": "24px",
      "dark": "24px"
    },
    {
      "name": "--cds-space-20",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-type-body-small-size",
      "light": "0.875rem",
      "dark": "0.875rem"
    },
    {
      "name": "--cds-brand",
      "light": "#ff550c",
      "dark": "#ff550c"
    },
    {
      "name": "--cds-brand-subtle",
      "light": "rgba(255, 85, 12, 0.15)",
      "dark": "rgba(255, 85, 12, 0.15)"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Playground](/storybook/iframe.html?id=cloaked-design-system-status-timeline--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Default](/storybook/iframe.html?id=cloaked-design-system-status-timeline--default&viewMode=story) | export: Default | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Complete](/storybook/iframe.html?id=cloaked-design-system-status-timeline--complete&viewMode=story) | export: Complete | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [With Icons](/storybook/iframe.html?id=cloaked-design-system-status-timeline--with-icons&viewMode=story) | export: WithIcons | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Compact](/storybook/iframe.html?id=cloaked-design-system-status-timeline--compact&viewMode=story) | export: Compact | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Horizontal](/storybook/iframe.html?id=cloaked-design-system-status-timeline--horizontal&viewMode=story) | export: Horizontal | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Single Item](/storybook/iframe.html?id=cloaked-design-system-status-timeline--single-item&viewMode=story) | export: SingleItem | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Long Text](/storybook/iframe.html?id=cloaked-design-system-status-timeline--long-text&viewMode=story) | export: LongText | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Horizontal Overflow](/storybook/iframe.html?id=cloaked-design-system-status-timeline--horizontal-overflow&viewMode=story) | export: HorizontalOverflow | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-status-timeline--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/status/Timeline/Timeline.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.