xlsx

A spreadsheet built by typing values into cells drifts into the raw-grid wall: heavy gridlines over numbers in no consistent format, with per-cell styling that varies run to run. Splitting the work keeps the drift out. The model decides the structure and supplies the data, and a fixed script renders the styling the same way every time. A JSON spec carries the model's decisions, and scripts/render.py turns that spec into a workbook with one reused header style, a frozen header row, content-sized columns, and the per-column number formats the spec names.

Design decisions live in the script and data decisions in the spec. The depth bar for the design system, the archetypes, and the failure modes lives in references/beautiful-spreadsheets.md, grounded in the foundation determinism doctrine.

Steps

1. State the workbook's purpose and its sheets. Name which spreadsheet this is (data table or tabular report) and list the sheets with their columns, drawing the archetype from the reference. This step ends when the sheet names and the per-sheet column lists are written down ahead of the spec.

2. Assemble the data into a JSON spec. Build one spec object whose sheets list holds an entry per sheet, each carrying a name, a columns list, a rows list of row arrays, and a number_formats map from column name to format string. Keep every row's length within the column count, and choose one format per numeric column from the table in the reference. This step ends when the spec is valid JSON whose every row fits its columns and whose every number-format key names a real column.

3. Render the workbook deterministically. Run scripts/render.py build <spec.json> <out.xlsx> to write the styled workbook from the spec. The script applies the bold filled header, freezes the header row at A2, sizes columns to their content, and stamps the per-column number formats; no styling is hand-written per run. This step ends when the command exits zero and prints the written workbook path.

4. Verify the artifact by reopening it. Reopen the saved .xlsx with openpyxl.load_workbook, then confirm the sheet names, the header cells, a sampled data value, and the frozen pane match the spec from step 1. This step ends when the reopened workbook reports the expected sheets, a header cell equal to its column name, a data cell equal to its spec value, and freeze_panes equal to A2.

Scripts

scripts/render.py is the deterministic renderer. Define the data and structure in a JSON spec, then let the script own all styling.