## Project Overview

Skylark Law needed a public-facing version of the official Massachusetts Child Support Guidelines Worksheet: a multi-step form that collects inputs, performs the required calculations accurately, and generates a printable PDF that matches the worksheet layout closely enough to be useful in real client work.

The original brief was practical: the Gravity Forms calculation logic was becoming slow and brittle, and the client wanted the output downloadable as a PDF in the same format as the official worksheet.

## Scope

- Implemented a Gravity Forms-based, multi-page calculator that prioritizes speed and correctness over "clever" front-end math.
- Built a PDF output pipeline using Gravity PDF (mPDF under the hood) with a custom template matching the worksheet layout.
- Maintained the calculator through guideline updates with distinct iterations aligned to major worksheet changes (2018 → 2021 → 2025).

## Challenge

- **Performance**: heavy client-side calculations (especially across many dependent fields) can make a form feel sluggish, which undermines trust in the result.
- **Accuracy**: legal/financial calculators need consistent rounding rules, correct thresholds, and reliable edge-case behavior (zero income, caps, boundary values).
- **PDF fidelity**: "export to PDF" isn't useful if the printout doesn't match the worksheet structure clients expect to see.

## Constraints & Context

- The build had to use **Gravity Forms** (as the form engine) and a **Gravity PDF** workflow for PDF output.
- The PDF layout needed to align very closely with the official worksheet (multi-page, exact placements, and consistent fonts).
- The UI needed to stay responsive, while calculations remained deterministically correct.

## Solution

We solved this by moving the "source of truth" for calculations into server-side PHP, and by treating each guideline update as a versioned ruleset instead of a risky in-place rewrite.

**1) Server-driven calculations to keep the UX fast**

Gravity Forms can calculate fields in JavaScript, but when you have dozens of interdependent fields and conditional branches, the front-end can slow down quickly. To keep the form responsive, we computed derived values in PHP during the form render cycle (`gform_pre_render_*`) and wrote the computed values back into the form defaults (and `$_POST`) so the next page loads with the correct results. This dramatically reduces the browser's calculation burden and makes the behavior consistent across devices.

**2) Guardrails: validation, caps, rounding, and "N/A" handling**

We added explicit validation rules where users can accidentally create impossible states (e.g., child counts not matching custody scenarios) and enforced clear boundary conditions. For example: income caps (which change by guideline year), low-income thresholds, minimum support amounts, and benchmark caps. We also handled "N/A" fields predictably and ensured formatting stayed consistent (e.g., whole-dollar currency formatting on the calculator pages).

**3) Versioned guideline logic (2018 → 2021 → 2025)**

Instead of trying to maintain one giant function forever, we kept the major guideline updates as distinct implementations. The 2021 and 2025 updates include concrete rule changes (thresholds, caps, and Table A schedule updates). In 2025, the Social Security dependency benefit section was restructured and required both UI logic (enable/disable fields based on Yes/No selection) and calculation updates (using 2c instead of 2b for specific downstream formulas). This approach made each update reviewable and safer to ship.

**4) PDF output that matches the worksheet**

For PDF generation we used Gravity PDF (mPDF) with a custom template that places form values onto a background image of the official worksheet pages. That gives a high-fidelity printout: the PDF renders as a four-page worksheet, with values positioned in the correct boxes. For the 2025 edition, we added the new "Worksheet Summary" section at the top of page one and conditionally rendered checkboxes based on the calculated results (e.g., high-income threshold and substantial hardship deviation).

**5) Testing as a first-class deliverable**

Because this is a legal calculator, we documented a boundary-focused testing checklist (income bracket edges, cap boundaries, threshold edges, and representative full scenarios) so future guideline updates can be validated quickly and confidently.

## Results

The client was happy with the result, and we've continued to support the calculator through multiple guideline updates—shipping three major iterations as Massachusetts updated the official worksheet.