# Waterfall Chart — Chart-Specific Rules

> Extends the global rules in [data-visualization-guide.md](../data-visualization-guide.md). All global rules apply. This file adds waterfall-specific bar, baseline, threshold, and label details.

---

## Overview

A waterfall chart shows per-subject or per-sample change from baseline. Bars are sorted ascending so the best responders appear on the left. Commonly used in oncology to visualize tumor response.

---

## Bar Layout

- Sort all bars **ascending by value** before rendering (most negative on left)
- Each bar anchors at the **zero baseline** and extends:
  - **Downward** for negative values (response / reduction)
  - **Upward** for positive values (progression / increase)
- All four corners rounded at **3px**
- **Fill:** 100 stop of the bar's color scale
- **Stroke:** 300 stop, **1px** weight

---

## Bar Sizing

- Bar width scales with the number of subjects: approximately `320px / n` clamped between 12px and 28px
- Gap between bars: approximately 20% of bar width, minimum 2px

---

## Zero Baseline

- Rendered as a full-width horizontal gridline using the `border-strong` token at 1px
- This gridline serves as the x-axis reference — no separate x-axis spine is needed

---

## Y Axis

- Symmetric about zero: the nice-scale maximum applies equally to the positive and negative ranges
- Show y-axis spine on the left edge with **8px upward overhang**
- Tick labels include sign: `+20%`, `-30%`, `0%`
- **Left margin:** Use `MARGIN.left = 68` to give the rotated y-axis title and signed tick labels (e.g., `+80%`) at least 13px of clear space between them. Do not reduce — tight left margins cause the axis title and tick values to collide.

---

## Clinical Threshold Lines (Optional)

Dashed reference lines marking clinical decision boundaries:

| Threshold | Typical Value | Color |
|---|---|---|
| Partial Response (PR) | −30% | Blue 300/500 |
| Progressive Disease (PD) | +20% | Orange 300/500 |

- **Stroke weight:** 1px
- **Dash pattern:** 4px on / 3px off
- Label inline at the right edge of the plot area (e.g., `PR −30%`, `PD +20%`)

---

## Patient / Sample Labels

- Render below the zero baseline (below the chart bottom)
- Rotated **−45°** from the bar's center x position
- Font size: 9px, Figtree Regular, secondary text color

---

## Legends

- The waterfall chart does not typically use a legend unless bars are colored by group/compound
- When a legend is needed, place below the chart and center over the plot area

---

## Notes

*Add agent or design team notes here as waterfall chart conventions evolve.*