# Waterfall Running Total Verification Mechanism in Diagram-Design

> Learn about the waterfall running total verification mechanism in diagram design. This nine-step pipeline ensures SVG waterfall charts maintain mathematical integrity by validating declared data values against rendered geometry.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-11

---

**The waterfall running total verification mechanism is a nine-step pipeline implemented in [`scripts/verify-waterfall.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-waterfall.py) that ensures SVG waterfall charts maintain mathematical integrity by validating that declared data values match rendered geometry within strict tolerances.**

The cathrynlavery/diagram-design repository employs a comprehensive waterfall running total verification mechanism to guarantee that every waterfall chart accurately represents its underlying data. This system parses SVG elements, computes running totals from delta values, and enforces visual consistency rules to prevent discrepancies between data declarations and rendered output.

## Pipeline Architecture

The verification logic lives in [`scripts/verify-waterfall.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-waterfall.py) and processes each HTML file through a strict sequence of checks. The **overall invariant** demands that declared data (`data-value`, `data-carry`) and rendered geometry (positions, heights, colours) agree exactly, with zero tolerance for numeric discrepancies and only a minimal ±0.75 px tolerance for rounding artefacts.

### 1. SVG Parsing and Metadata Extraction

The pipeline begins by extracting all visual elements and their semantic attributes. The `parse_bars()` function uses `RECT_RE` to identify every `<rect>` element (bars), while `parse_number()` uses `LINE_RE` to locate `<line>` elements (carries). The parser captures:

- `data-role`, `data-value`, `data-carry`, and `data-name` attributes
- Geometry attributes (x, y, width, height)
- Style information and CSS transform maps

This step builds an internal representation of the chart structure before any validation occurs.

### 2. Structural Validation

The `check_structure()` function enforces the grammatical rules of waterfall charts. It verifies that the chart contains at least a start total, one delta, and an end total. All totals must be positive numbers, while deltas must carry explicit signs (e.g., `+64` or `-12`). The function also validates that the total number of bars and subtotals remains within the defined budget constraints.

### 3. Transform Detection

Geometric integrity requires that coordinates remain static after calculation. The `check_transforms()` function scans for SVG `<g>` or `<svg>` groups containing `transform` or `style` attributes that would shift bar or carry positions after coordinate baking. If detected, the verifier reports a failure because the script would see different geometry than the browser renders.

### 4. Running Total Computation

The `running_levels()` function walks the declared bars from left-to-right, adding or subtracting each delta to maintain an accurate **running total**. It returns a list of `(level_before, level_after)` tuples for every bar. If any step produces a non-finite or negative total, the verification aborts immediately.

### 5. Scale Calculation and Geometry Verification

Using the start total’s height as a reference, the script calculates a shared scale factor:

```python
scale = start.h / start.value

```

The `check_geometry()` function then recomputes expected top and bottom Y-coordinates for every bar using this scale. It validates that actual `y` and `height` values match expectations within `GEOMETRY_TOLERANCE` (±0.75 px).

### 6. Carry Line Validation

Between adjacent bars, horizontal `<line>` elements with `data-carry` attributes must bridge the gaps accurately. The `check_carries()` function verifies that:

- Each line spans the complete horizontal gap between bars
- The declared `data-carry` value matches the computed running level
- The Y-position aligns with `baseline - scale * level`

### 7. Printed Value Verification

The `printed_values()` and `check_printed()` functions scan `<text>` elements positioned on bars. They strip markup, parse the displayed number, and confirm that the printed value—including explicit signs for deltas—matches the bar’s declared `data-value`.

### 8. Sign Treatment and Visual Consistency

The `check_sign_treatment()` function enforces the visual grammar of waterfall charts. It confirms that positive and negative deltas use distinct fill colours (tint versus paper) and that at most one bar receives the accent stroke. The function also validates colour mappings across the two supported themes.

### 9. Error Aggregation and Reporting

The `verify_file()` and `main()` functions collect all validation errors into a list. If no errors are found, the script reports `OK`. Otherwise, it prints detailed diagnostic messages per file before exiting.

## Command-Line Usage

Verify a single waterfall HTML file:

```bash
python3 scripts/verify-waterfall.py skills/diagram-design/assets/example-waterfall.html

```

Verify all shipped examples in the repository:

```bash
python3 scripts/verify-waterfall.py --all

```

Successful verification outputs:

```

OK skills/diagram-design/assets/example-waterfall.html

```

## Programmatic Integration

Import the verification logic directly into Python applications:

```python
from pathlib import Path
from scripts.verify_waterfall import verify_file

# Load an HTML file and get a list of validation errors (empty list = success)

errors = verify_file(Path("skills/diagram-design/assets/example-waterfall.html"))
if errors:
    print("Found problems:")
    for e in errors:
        print("  -", e)
else:
    print("Waterfall passes all checks")

```

## Common Validation Errors

When a delta lacks an explicit sign in its `data-value`, the `parse_signed()` function returns `signed=False`, triggering `check_structure()` to report:

```

'Headcount': a delta must declare an explicit sign in data-value; got "64"

```

If a carry line's Y-coordinate deviates from the calculated level, `check_carries()` produces:

```

gap between 'Headcount' and 'Reserved inst.': carry drawn at y=140 but the 304 level sits at y=130.5

```

Missing carry lines between bars generate:

```

carry 240: no carry spans it

```

## Summary

- The waterfall running total verification mechanism processes charts through nine sequential checks in [`scripts/verify-waterfall.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-waterfall.py).
- **MATLAB**: The system validates mathematical integrity by computing running totals via `running_levels()` and verifying geometry against a shared scale derived from the start total.
- **Strict parsing** requires explicit signs for all delta values and detects illegal CSS transforms that could alter rendered geometry.
- **Sub-pixel precision** allows ±0.75 px tolerance for rounding artefacts, but enforces zero tolerance on numeric data mismatches.
- The verifier supports both command-line batch processing (`--all`) and programmatic integration via `verify_file()`.

## Frequently Asked Questions

### What triggers a "delta must declare an explicit sign" error?

This error occurs when the `data-value` attribute of a delta bar contains a number without a leading `+` or `-` sign. According to the waterfall grammar defined in [`docs/adr/0011-waterfall-is-a-running-total-grammar.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0011-waterfall-is-a-running-total-grammar.md), all delta values must explicitly declare their direction to ensure unambiguous running total calculations. The `parse_signed()` function checks for this prefix, and `check_structure()` reports the violation if missing.

### How does the verifier handle CSS transforms on chart elements?

The `check_transforms()` function actively scans for `transform` attributes or inline styles on `<g>` and `<svg>` elements that would modify coordinates after the initial geometry calculation. If detected, verification fails immediately because such transforms create a discrepancy between the coordinates seen by the verifier and those rendered by the browser. All geometric positioning must be baked into element attributes before verification.

### What is the significance of the 0.75 pixel tolerance in geometry checks?

The `GEOMETRY_TOLERANCE` constant (±0.75 px) accounts for floating-point rounding differences between JavaScript rendering engines and Python calculation logic. While numeric data values must match exactly with zero tolerance, minor sub-pixel deviations in SVG coordinate calculations are permissible. This tolerance prevents false negatives while maintaining strict visual accuracy standards.

### Can the verification script process multiple waterfall charts simultaneously?

Yes. Running `python3 scripts/verify-waterfall.py --all` processes every shipped example in the repository sequentially. The `main()` function iterates through all target files, aggregates errors per file, and provides a comprehensive report. For CI/CD pipelines, the script exits with a non-zero status if any validation fails, making it suitable for automated quality gates.