Skip to content

Numbered Steps Timeline

Status: Canonical Applies to: Marketing flows, onboarding wizards, instructional walkthroughs, multi-step demos

Purpose

The Numbered Steps Timeline communicates a sequential process where each step has a distinct phase, outcome, and optional call-to-action.

It must:

  • Show progression -- a vertical connector line ties steps into a narrative
  • Label each phase -- uppercase phase name grounds the step in the workflow
  • Collapse gracefully -- fewer steps should not produce awkward gaps
  • Link outward -- each step may include action cards pointing to artifacts

SageOx adopts the blog-post variant as canonical: static gradient connector, halo-ringed number dots, no scroll-driven animation.

Anatomy

  ●─ Phase Label (uppercase, tracked)
  │  Title (bold heading)
  │  Description (muted body text)
  │  [Icon  Action card  ↗]
  │
  ●─ Phase Label
  │  Title
  │  ...

Parts

Part Required Description
Number dot Yes Circular badge with step number (1-based)
Phase label Yes Uppercase keyword for the workflow phase
Title Yes Bold heading describing the step outcome
Description Yes 1-2 sentences explaining what happens
Action card No Link button with icon + external arrow
Connector line Yes Vertical line connecting all dots

Tokens & Dimensions

Number Dot

Property Value Token
Size 30 x 30px --
Border radius 50% (circle) radius.full
Background sage-500 --ox-connector-dot-border
Text color #fff --
Font Space Grotesk font-heading
Font size 0.72rem (~11.5px) --
Font weight 700 --
Halo ring box-shadow: 0 0 0 4px rgba(74,95,61,0.1) --
z-index 1 (above connector line) --

Connector Line

Property Value Token
Width 2px --
Position Centered behind number dots --
Top/bottom inset 8px from first/last dot center --
Background Gradient fade at endpoints See below
Border radius 1px --

Connector gradient (canonical):

background: linear-gradient(
  to bottom,
  var(--ox-border),           /* fade in from border color */
  rgba(74, 95, 61, 0.3),     /* sage midpoint, reduced opacity */
  var(--ox-border)            /* fade out to border color */
);

The gradient prevents hard-starting/stopping lines and communicates that the timeline is a flow, not a stack.

Phase Label

Property Value Token
Font Space Grotesk font-heading
Font size 0.65rem (~10.4px) --
Font weight 600 --
Text transform uppercase --
Letter spacing 0.1em --
Color sage-800 --ox-text-heading
Bottom margin 0.2rem --

Title

Property Value Token
Font Space Grotesk font-heading
Font size 1.05rem (~16.8px) --
Font weight 700 --
Letter spacing -0.01em --
Color sage-800 --ox-text-heading
Bottom margin 0.3rem --

Description

Property Value Token
Font Inter font-body
Font size 0.86rem (~13.8px) --
Line height 1.6 --
Color silt-600 --ox-text-muted
Max width 580px Prevents overly long lines
Property Value Token
Display inline-flex, center-aligned --
Padding 0.5rem 0.9rem (8px 14.4px) --
Background sage-50 --ox-accent-surface
Border 1px solid --ox-border
Border radius 8px radius.lg
Font size 0.82rem (~13px) --
Font weight 500 --
Color sage-800 --ox-text-heading
Icon size 15 x 15px, opacity 0.6 --
Arrow icon 12 x 12px, opacity 0.5 --
Transition border-color, box-shadow, background 250ms animation.duration.normal

Hover state:

Property Value
Border color rgba(74, 95, 61, 0.4)
Box shadow 0 2px 12px rgba(74, 95, 61, 0.1)
Arrow translateX(2px) over 200ms

Layout

Desktop (>600px)

Property Value
Steps container left padding 52px (clears dot + gap)
Connector line left 15px (centers under 30px dot)
Number dot left offset -52px from content edge
Step bottom margin 1.8rem (28.8px)
Last step bottom margin 0

Mobile (≤600px)

Property Value
Steps container left padding 42px
Connector line left 11px
Number dot left offset -42px
Number dot size 26 x 26px
Number dot font size 0.68rem

Container (When Used as a Widget)

The timeline may be wrapped in a demo container card:

Property Value Token
Background sage-200 --ox-surface-2
Border 1px solid --ox-border
Border radius 16px radius.2xl
Padding 2.5rem 2rem 2rem --
Overflow hidden --

The container supports an optional gradient overlay (see Gradient Overlays).

An optional badge pill may appear above the steps:

Property Value Token
Padding 0.3rem 0.85rem --
Border 1px solid --ox-border
Border radius 100px (pill) radius.full
Font size 0.72rem --
Background sage-200 --ox-surface-2
Pulse dot 6px circle, sage-800, 2s pulse animation --

Behavior

Static (Canonical)

All steps are visible and expanded by default. No scroll-driven reveal, no collapse/expand animation. This is the canonical behavior for marketing and documentation contexts.

Animated (Optional, Marketing Landing Only)

When scroll-driven reveal is justified (e.g., a hero demo walkthrough):

  • Use IntersectionObserver to track which steps are in viewport
  • Number dots transition from bg-ox-border → bg-ox-connector-dot-border + scale(1.1) + shadow-md
  • Content expands via max-height transition (0 → 900px, 500ms ease)
  • Title slides in from -translateX(2px) + opacity: 0
  • Progress fill overlays the static track line, height computed from visible step indices

Animated behavior must not be the default. It is reserved for single-use landing page storytelling where progressive disclosure serves the narrative.

Anti-Patterns

Pattern Why It Fails
Horizontal stepper Breaks on mobile, limits description length
Accordion collapse on visited steps Hides context the user may want to re-read
Numbered list without connector line Loses visual continuity between steps
Dots without halo ring Dots feel disconnected from the line
Auto-advancing steps on timer Violates user control principle
More than 6 steps Sequence is too long; restructure into phases

Accessibility

  • Number dots must have aria-label="Step {n}: {phase}" or equivalent
  • Action cards must be focusable with visible focus ring
  • Connector line is decorative (aria-hidden="true")
  • Color alone must not communicate step state; active vs inactive must also be communicated via text or ARIA attributes