nexu-io/open-design · error · OverflowError

cursor at exceeds footer rail ; reduce block height or…

Error message

cursor at {self.y} exceeds footer rail {self.cap}; reduce block height or split slide

What it means

Raised by the Cursor.take() helper documented in skills/pptx-html-fidelity-audit/SKILL.md when advancing the content cursor would push self.y past self.cap (CONTENT_MAX_Y, the footer rail). It is an intentional OverflowError that turns a silent visual overflow (content crossing the footer) into a loud build error during pptx re-export.

Solutions

Reduce the offending block's height (tighten image height, trim text, shrink padding).
Split the slide into two slides so each fits within the rail.
Raise CONTENT_MAX_Y only if the design system genuinely allows a smaller footer (update FOOTER_TOP accordingly and pass --content-max-y to verify_layout.py).
Switch the slide to hero_layout (centered budget) if it is a vertically-centered hero, not a top-pinned flow.

Example fix

# before
cursor = Cursor(MARGIN_TOP)
cursor.take(Inches(6.5))   # single block too tall, raises OverflowError
# after
cursor.take(Inches(3.0))
cursor.take(Inches(2.8))   # split into two blocks that fit

Defensive patterns

Strategy: try-catch

Validate before calling

if cursor.y + h + gap > cursor.cap:
    raise SystemExit(f"block of height {h} would overflow footer rail; split or shrink")

Try / catch

try:
    top = cursor.take(block_height)
except OverflowError as e:
    # split the slide or shrink the block, then retry
    split_or_shrink(block, e)
    raise

Prevention

Compute per-block heights from text metrics + minimal padding, not generous wrappers.
Keep CONTENT_MAX_Y and FOOTER_TOP defined once per deck and passed to verify_layout.py.
Use hero_layout for centered slides instead of a top-pinned Cursor.
Run verify_layout.py after every re-export so overflows are caught early.

When it happens

Trigger: Calling cursor.take(h) for a block whose height plus gap pushes the running y beyond CONTENT_MAX_Y; too many blocks stacked in reading order; a single oversized block (e.g. a tall image or long bullet list).

Common situations: Re-exporting a deck where a slide has more content than the content area allows; design system changed footer height so CONTENT_MAX_Y shrank; image heights computed too generously.

Related errors

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/65052b9ce971e9aa. Report an issue: GitHub.

Appendix: source

Thrown at skills/pptx-html-fidelity-audit/SKILL.md:136

FOOTER_TOP     = Inches(6.85)     # footer row pinned here, edge-to-edge
```

> **Customizing the rails.** The defaults above suit a 16:9 canvas with a slim footer. If your design system uses a wider footer or a 4:3 canvas, override these constants in your export script and pass the same values to `verify_layout.py` via `--content-max-y` / `--canvas-h` / `--canvas-w`. See `references/layout-discipline.md` §1 for the full constant table.


**Use a cursor for content blocks instead of pinning each block at an absolute y:**

```python
class Cursor:
    """Advances down the slide; refuses to cross the footer rail."""
    def __init__(self, y_start, cap=CONTENT_MAX_Y):
        self.y = y_start
        self.cap = cap
    def take(self, h, gap=Inches(0.12)):  # ~1 line of whitespace at 14pt; tighten/loosen per design system
        top = self.y
        self.y = top + h + gap
        if self.y > self.cap:
            raise OverflowError(
                f"cursor at {self.y} exceeds footer rail {self.cap}; "
                f"reduce block height or split slide"
            )
        return top
```

For each slide, instantiate `Cursor(MARGIN_TOP)` and `take(height)` each block in reading order. The slide refuses to render if any block would cross the rail, so overflows become loud build errors instead of silent visual bugs.

**Hero (vertically-centered) slides use a budget instead of a cursor:**

```python
def hero_layout(blocks):
    """blocks = list of (height, gap_after) tuples in reading order."""
    total = sum(h + g for h, g in blocks)
    y_start = (CANVAS_H - total) / 2
    return Cursor(y_start)
```

View on GitHub (pinned to 5be4028344)