This guide treats those seams as explicit contracts. A compact fixture window—November and December 2026, followed by January and February 2027—crosses a year boundary, a Sunday-start month, and a common-year February. It gives a reproducible starting point for failures that otherwise get dismissed as ‘works on my machine.’

A boundary fixture

The values below use Gregorian dates and Monday-first weeks. Natural grids use the minimum whole number of rows; fixed grids reserve six rows.

For a day whose weekday index is w and a configured week start s, the leading offset is (w - s) % 7. With D days, the natural row count is (offset + D + 6) // 7. Fixed mode has 42 slots. These are different display policies; don’t let a renderer switch between them implicitly.

Fifteen failures worth making visible

1. Wrong weekday offset. A Sunday-first index is passed to a Monday-first grid. Assert the normalized offset for all seven week starts.
2. Time-zone date shift. A civil date is stored as UTC midnight and reformatted west of UTC. Keep month topology in date-only values; test that changing the process time zone does not move a day.
3. Fixed-grid overflow. The renderer adds a seventh row instead of enforcing 42 slots. Assert both slot count and current-month day count.
4. Stale natural-grid height. A six-row month changes to four rows but retains the old cell height. Derive cell height from the actual row count each render.
5. Treating six rows as the month definition. Fixed and natural grids serve different layouts. Test each policy separately.
6. Leap-year mistakes. A divisibility-by-four shortcut makes 1900 incorrectly leap. Check 1900, 2000, 2024 and 2027.
7. Year rollover defects. Incrementing December to month 13 skips January. Assert the chronological sequence (2026, 12) → (2027, 1).
8. Paper aspect-ratio reuse. A4 and US Letter have different proportions. Recalculate from each page box, not width alone.
9. Print-margin clipping. CSS page margins cannot enlarge a printer’s imageable area. Keep critical content inside a safe inset and verify at 100%.
10. SVG physical-size mismatch. A correct viewBox does not set the physical sheet. Check outer width and height as well as aspect ratio.
11. PDF page-box mismatch. Keep the PDF MediaBox derived from the same paper model as SVG; Letter is 612 × 792 points, A4 about 595.28 × 841.89.
12. Writing-space collapse. Title, weekday labels and notes consume the grid area. Assert minimum cell dimensions after reserving these regions.
13. Adjacent-month ambiguity. A zero or duplicated neighboring date is not an empty slot. Represent out-of-month cells explicitly.
14. Locale mismatch. Runtime defaults can change week starts and labels. Make both explicit inputs and verify header order against date placement.
15. Screen/print divergence. Screen-only controls or dark backgrounds leak into print. Test the print stylesheet and the page box independently from the viewport.

The page is not the viewport

A responsive screen grid can be fluid; a paper layout has fixed dimensions, margins and printer constraints. Use millimetres, inches or points for page-level geometry, and convert once. CSS defines one inch as 96 CSS pixels and one point as 1/72 inch. SVG’s viewBox describes drawing coordinates, while its outer dimensions describe the viewport. PDF pages use points. They are related coordinate systems, not interchangeable declarations.

A basic print profile could be: @page { size: A4 portrait; margin: 12mm; }. Reserve the margins before dividing the remaining body into rows. The browser can request A4; it cannot guarantee borderless printing. Keep essential rules and labels away from sheet edges, and state whether “fit to page” scaling is acceptable because it changes writing-cell size.

Make failures reproducible

Record year, month, week start, grid policy, paper, orientation, margins, notes area and renderer version with every failing output. ‘February is broken’ is not enough. A useful fixture says, for example: 2027-02, Sunday-first, natural grid, Letter landscape, 12 mm margins, notes enabled. Then assert the expected day sequence, row count, cell bounds and serialized page box.

Keep checks layered: first date topology; then positive geometry and containment; then SVG/PDF page dimensions; finally visual and physical print checks. A screenshot can reveal a clipped numeral, but it cannot prove that a PDF is 210 mm wide. For a device proof, print a ruler and safe-area marks at actual size, measure them, and record the printer and scaling setting. A driver can shrink a correct PDF, and a hardware margin can clip content that remains inside the nominal page.

Test boundaries by name as well as with broad property loops. November 2026 exercises a Sunday start and six natural rows. December-to-January catches the civil-year transition. February 2027 verifies common-year length and a four-row natural grid. Add separate leap-century cases; don’t infer leap behavior from the year-turn fixture. Include all seven week starts so a locale default cannot hide in the host environment.

The architecture and deterministic pipeline article describes how to separate civil dates, grid topology, layout constraints and rendering. Here are useful human-readable comparisons: November, December, January, February, and the blank calendar layout.

References

• Python date and datetime documentation
• W3C CSS Values and Units
• W3C SVG coordinate systems
• W3C CSS Paged Media
• ISO 216 paper sizes
• US National Archives: Letter dimensions

The useful mental model is a pipeline:

CivilDate → MonthTopology → WeekGrid → LayoutConstraints → PaperGeometry → SVG/PDF/Print → Validation

Each stage has a narrow contract. When a rendering bug appears, those contracts make it possible to tell whether the error came from date arithmetic, grid policy, geometry or output conversion.

Start with civil dates, not timestamps

A calendar page describes civil dates. A month is a year and month in a calendar system; it is not an interval of UTC instants. Turning “January 1” into midnight UTC and then formatting it in a western time zone can display December 31. The conversion is internally consistent, but it answers a different question.

Keep the calendar model in date-only values. In Python, datetime.date models a proleptic Gregorian date and has no time-of-day or time-zone component. Its weekday() method numbers Monday as zero through Sunday as six. That makes it a useful boundary type for month topology. Use timestamps only at actual event boundaries, and convert them to the intended civil zone before extracting a date.

The Gregorian month length is determined by the year and month. A leap year is divisible by four, except century years unless divisible by 400. This rule should live in one tested function rather than being reconstructed inside a view template.

from calendar import monthrange
from datetime import date


def days_in_month(year: int, month: int) -> int:
    if not 1 <= month <= 12:
        raise ValueError("month must be in 1..12")
    return monthrange(year, month)[1]


def monday_offset(year: int, month: int, week_starts_on: int = 0) -> int:
    """Return leading cells before day 1; Monday=0 ... Sunday=6."""
    if not 0 <= week_starts_on <= 6:
        raise ValueError("week_starts_on must be in 0..6")
    first_weekday = date(year, month, 1).weekday()
    return (first_weekday - week_starts_on) % 7

The modulo operation is the normalization step. If a month starts on Friday (weekday 4) and the week begins Monday (0), four leading cells are needed. If the week starts Sunday (6), the same Friday start needs five. The month did not change; only the presentation convention did.

Month topology is separate from grid policy

For a month with D days and leading offset L, the minimum row count is:

rows = ceil((L + D) / 7) = (L + D + 6) // 7

A natural grid uses that minimum number of rows. It avoids empty rows, but its height varies between four, five and six weeks. A fixed grid always reserves six rows, yielding a 42-cell invariant. Fixed grids align every month in a multi-month layout and simplify downstream drawing; natural grids can give each day a taller cell on a single-month sheet.

These are product choices, not competing definitions of a month. A renderer should accept a grid policy explicitly instead of silently padding or trimming. In a natural grid, storage can still be padded to whole rows; only the visible row count changes.

def build_month_grid(year: int, month: int, week_starts_on: int = 0,
                     fixed_six_rows: bool = False) -> list[list[int | None]]:
    count = days_in_month(year, month)
    offset = monday_offset(year, month, week_starts_on)
    rows = 6 if fixed_six_rows else (offset + count + 6) // 7
    slots: list[int | None] = [None] * offset + list(range(1, count + 1))
    slots += [None] * (rows * 7 - len(slots))
    return [slots[i:i + 7] for i in range(0, len(slots), 7)]

The null cells are intentional. They mean “outside this month,” not the last day of the previous month and not a zero-valued date. Keeping that distinction in the model lets an adjacent-month design opt in to neighboring dates later, without corrupting the basic month grid.

For every valid month, the following invariants should hold:

• Flattening the grid and removing empty cells yields exactly 1..D, in order.

• Every row has seven positions.

• The number of current-month cells is D.

• A fixed grid has exactly six rows and 42 positions.

• A natural grid has the minimum row count from the equation above.

Paper geometry is a separate coordinate system

A4 portrait is 210 × 297 mm. US Letter portrait is 8.5 × 11 inches, or 215.9 × 279.4 mm. The paper choice changes the usable shape: Letter is wider and shorter than A4. A layout that works on one is not proven on the other.

Start with page dimensions, subtract margins and reserve any title, weekday-label, notes or footer regions. The remainder is the calendar grid’s usable rectangle. If the grid has seven columns and R rows, a simple uniform cell has width grid_width / 7 and height grid_height / R. Validate that both are positive and above the product’s minimums for readable numerals and handwriting.

from dataclasses import dataclass

@dataclass(frozen=True)
class Paper:
    width_mm: float
    height_mm: float

@dataclass(frozen=True)
class Insets:
    top_mm: float
    right_mm: float
    bottom_mm: float
    left_mm: float

A4 = Paper(210.0, 297.0)
US_LETTER = Paper(215.9, 279.4)


def usable_area(paper: Paper, inset: Insets, title_mm: float,
                weekday_header_mm: float, notes_mm: float = 0) -> tuple[float, float]:
    width = paper.width_mm - inset.left_mm - inset.right_mm
    height = (paper.height_mm - inset.top_mm - inset.bottom_mm
              - title_mm - weekday_header_mm - notes_mm)
    if width <= 0 or height <= 0:
        raise ValueError("margins and reserved regions consume the page")
    return width, height

Portrait and landscape are not just rotations of a preview screenshot. They alter the ratio available to the grid and often change what “comfortable writing space” means. Treat orientation as a transform of page dimensions before computing layout. Do not rotate only the final image and expect text or margins to stay correct.

The CSS absolute units define useful conversions: 1 inch is 96 CSS pixels and 1 point is 1/72 inch. For print-oriented geometry, use millimetres, inches or points at the page boundary and convert once. Repeatedly rounding between units can introduce drift. Browser CSS pixels are a convenient screen coordinate, but a CSS pixel is not a promise that a home printer will lay ink on a physical 1/96-inch square.

Turn the grid into a layout contract

The grid is a topological structure; assigning rectangles is a separate calculation. Let the safe page rectangle begin at (x₀, y₀) and have width W and height H. Reserve the title and weekday header before splitting the remainder into R equal rows. For column c and row r, the cell origin is x₀ + c(W/7) and y₀ + r(H/R). Derive every edge from the same origin and step instead of accumulating rounded widths. If the first six columns are rounded independently, the seventh can end one or more device pixels outside the intended boundary.

For handwriting-first calendars, equal cells are a starting point rather than a final design. A title band, weekday row, calendar body and notes region can have different heights. Model them as named regions, then subdivide only the body into date rows. That makes a notes area a real input instead of a late CSS override. It also gives tests stable objects to inspect: a page rectangle, safe rectangle, title rectangle, weekday rectangle, body rectangle and optional notes rectangle.

A layout solver should fail clearly when constraints cannot be met. For example, choose a minimum cell height h_min from the product’s writing-space requirement. The usable calendar-body height must satisfy H_body >= R × h_min; otherwise the renderer can choose a different orientation, remove an optional notes area, or return a constraint error. Silently compressing the cells is the worst option because the PDF remains syntactically valid while the paper becomes unusable.

def cell_size(grid_width_mm: float, grid_height_mm: float,
              rows: int, columns: int = 7) -> tuple[float, float]:
    if rows <= 0 or columns != 7:
        raise ValueError("a month grid needs positive rows and seven columns")
    width, height = grid_width_mm / columns, grid_height_mm / rows
    if width <= 0 or height <= 0:
        raise ValueError("grid dimensions must be positive")
    return width, height

A renderer can keep geometry in floating-point millimetres or points through layout, then round only when rasterizing. SVG supports fractional user coordinates; PDF content streams also support decimal coordinates. Rounding each intermediate margin to a whole CSS pixel creates avoidable error, especially when the page is converted more than once.

Locale changes labels, not the underlying month

Week starts and weekday names are presentation inputs. A locale may imply Sunday-first weeks, localized month names, or a different abbreviation width. Do not let the host machine’s locale become an invisible default. Pass week_starts_on explicitly, choose the locale for labels separately, and keep ISO-like machine fixture values independent from translated UI text.

The week-start convention must be visible to readers. If the model is Monday-first but the header says Sunday first, the dates are numerically valid but misleading. Tests should verify the header order and the grid offset together. If Sunday-first is selected, Monday-indexed weekday() values still work after modulo normalization; only the configured start value changes.

Localization also affects page geometry. “Wednesday” may be wider than a two-letter abbreviation; a different script can need a different font fallback; right-to-left text may alter alignment without changing the seven-column sequence. Measure text after font selection, reserve a label region that accommodates the supported strings, and avoid baking translated labels into the date model. A label-overflow check is a typography test, while day placement remains a topology test.

SVG and PDF need an explicit physical contract

An SVG viewBox defines a user-space rectangle and maps it into the rendered viewport. It does not, by itself, guarantee the physical paper size. Give the outer SVG a physical width and height (for example, 210mm by 297mm) and a matching viewBox; then keep all drawing coordinates inside that coordinate system. This lets a browser scale the SVG for display while retaining a paper-sized page for print or PDF conversion.

For PDF, define the page box in points and make the content transform explicit. Since one point is 1/72 inch, a Letter page is 612 × 792 points. An A4 page is approximately 595.28 × 841.89 points. Keep the PDF page dimensions and the SVG physical dimensions derived from the same paper model; do not hard-code a separate set of numbers in a PDF exporter.

@page { size: A4 portrait; } communicates page intent to a browser print pipeline, while @media print can remove navigation, backgrounds or interactive controls. The printer’s non-printable region remains device-specific. A page can be correctly sized in CSS and still be clipped by a printer that cannot print to the edge. Offer a safe margin, avoid placing essential lines on the paper boundary, and make the “fit to page” behavior an explicit user choice because scaling changes cell size.

Reproducibility comes from contracts and fixtures

A deterministic renderer should take explicit inputs: year, month, week start, grid policy, paper, orientation, margins, reserved regions and output profile. It should not read the system time zone to decide where a date belongs or use locale defaults without recording them. Given the same inputs and version, it should produce the same geometry and content.

A small fixture set should cross temporal edges and layout variants. The following table is computed from Python’s Gregorian calendar implementation using Monday-first weeks; fixed mode reserves six rows in every case. The month references are human-readable comparisons for the rendered shape, not a substitute for numeric assertions.

The fixed-grid column means six rows for every month. For natural grids, a month may use fewer rows, and that difference must flow into cell height rather than be hidden by clipping. January 2027 begins on Friday; February begins on Monday and has 28 days. Those two months exercise different leading-space and height behavior.

Test the model before the pixels

Tests can validate the pure grid independently of typography:

from datetime import date
from calendar import monthrange

for year in range(1990, 2031):
    for month in range(1, 13):
        grid = build_month_grid(year, month)
        values = [value for row in grid for value in row if value is not None]
        assert values == list(range(1, monthrange(year, month)[1] + 1))
        assert all(len(row) == 7 for row in grid)
        fixed = build_month_grid(year, month, fixed_six_rows=True)
        assert len(fixed) == 6 and sum(len(row) for row in fixed) == 42

Then test the geometry model: positive usable dimensions, cells contained inside the grid rectangle, and grid bounds contained inside the printable safe area. Finally, render representative pages and compare both semantic output (dates, labels, page boxes) and visual output (clipping, contrast, line weights). A screenshot diff is useful, but it cannot prove that a PDF has the intended physical page size; inspect page metadata as well.

Accessibility belongs in this pipeline too. A calendar is a table-like structure, so preserve a meaningful reading order, label weekday columns with full accessible names where abbreviations are displayed, and do not use color alone to distinguish states. SVG should expose a title and description when embedded as an image, or the surrounding document should provide equivalent text. Printed output also needs enough contrast and line weight for ordinary printers.

The important design choice is not “SVG versus HTML.” It is whether every stage receives an explicit, testable contract. Civil dates determine month topology; topology determines a grid; layout constraints allocate space; paper geometry anchors the page; renderers serialize that model; validation checks each boundary. Once those responsibilities are separated, the output can be reproduced, compared and debugged without asking the browser to guess what a month means.

For the failure matrix covering paper clipping, week boundaries and regression fixtures, read The Calendar Layout Bugs You Only Find on Paper.

A useful implementation review can compare its visual grid with the blank calendar layout and the Beta Calendars project.

References

• Python datetime and date documentation

• W3C CSS Values and Units

• W3C SVG coordinate systems and viewBox

• W3C CSS Paged Media

• ISO 216 paper sizes

• US National Archives dimension authority: Letter paper