Pipeline Stages (HTML/CSS)
Best for: a left-to-right flow where each stage has its own components and the reader needs to see the order — ingest, transform, serve, and what fails where
Avoid when: the stages are really layers of one system → use layer-stack.md; or the relationships are many-to-many → use request-paths.md
Answers: what happens in what order, which stage owns which component, and where the flow can back up
Data Shape
One column per stage, in order, and one row per component inside it. The reader should be able to read the top line left to right and get the whole flow; the boxes underneath are detail, not the message.
Key Options
| Option | Effect |
|---|---|
A flex row of stage panels with a glyph between them |
The flow is the layout, so order survives a copy-paste or a narrow column |
A leading 1 · 2 · 3 · 4 badge on each stage heading |
Numbering is redundant coding — the order is readable without the arrows |
| A separate top row for sources | Keeps inputs from being mistaken for stages |
border-style: dashed for exits |
Distinguishes "the flow stops here" from "the flow continues" without a legend |
| A KPI row under the pipeline | Answers the follow-up question ("how fast, how often does it fail") in the same figure |
Pitfalls
- ❌ Putting the exit paths (reject, quarantine) in the arrow chain → ✅ they are exits; a dashed box inside the stage says so, an arrow out of the row implies a fifth stage
- ❌ More than five or six stages → ✅ group them; a pipeline diagram is about the shape of the flow, and every extra column makes each panel too narrow to read
- ❌ Using colour alone to mark the slow stage → ✅ the KPI row carries the number, and the box carries a word
- ❌ Drawing this as a layer stack because the columns are stacked vertically on a narrow screen → ✅ the
flex row wraps as a whole; if it must stack, that is
layer-stack.md
Alternatives
| Variant | Use instead |
|---|---|
| The same system by layer rather than by stage | layer-stack.md |
| Stage-to-stage relationships, including back-edges | request-paths.md |
| A CI/CD pipeline rather than a data pipeline | pipeline-stages.md with stages renamed, or basic-activity-flow.md |