jevangoldsmith.com

How We Build This Website

Status: canonical Audience: engineering, product, agents Purpose: define how to safely improve the website without changing style or behavior by accident

Build Philosophy

This website should feel hand-crafted to visitors and systematic to maintainers.

The public experience is the product. Refactors are successful only when the site looks and behaves the same, while the underlying authoring, performance, and safety rails improve.

Change Rules

1. Preserve current style unless a visual change is explicitly requested.
2. Preserve current behavior unless a product behavior change is explicitly requested.
3. Keep the public runtime static-first.
4. Prefer data/templates/components over repeated hand-edited markup.
5. Keep each public page owned by exactly one source file.
6. Run the full check gate before calling work complete.
7. Update docs when changing architecture, source ownership, deploy behavior, or reusable UI patterns.

Quality Gates

Every meaningful change should satisfy:

Gate	Requirement
Build	npm run build succeeds and updates generated artifacts.
Full check	npm run check passes.
Structure	npm run check:source and npm run check:structure pass.
Deploy surface	Firebase still serves dist/, not source folders.
Links	Local links resolve inside generated dist/.
Performance	Budgets pass or are intentionally ratcheted.
Behavior	Existing interaction contracts still hold.
Style	Design system language and visual patterns are preserved.

Generated Files Policy

Authored source:

• data/*.json, except generated data/pages.json
• _src/pages/, _src/layouts/, and _src/partials/
• css/src/
• js/
• scripts/
• docs/
• images/source/ master assets used to regenerate production images/video

Generated output:

• dist/
• css/style.css
• css/page-*.css
• images/generated/ responsive image and video derivatives
• data/pages.json
• sitemap.xml
• robots.txt
• llms.txt
• public .html files in dist/ generated from _src/pages/ or collection data

Do not hand-edit generated files. If a generated file is wrong, change the owning source file or the relevant build helper in scripts/build-site.js / scripts/build/, then run npm run build.

Asset derivatives are generated by npm run assets:optimize, which is also called by npm run build. Keep the source master crisp, regenerate derivatives, and let the build copy only production-safe generated assets into dist/.

Current commit policy: commit authored source only. Ignore generated deploy output, generated asset derivatives, remote asset caches, and generated indexes/bundles that can be recreated from source. robots.txt may stay tracked because it is tiny deploy metadata, but it is still generated by the build.

npm run check:source fails if a route exists in both the repository root and _src/pages/. data/source-ownership.json remains the contract for route ownership, even though legacy root page source has been cleared out. One page, one owner. npm run check:structure ratchets legacy CSS, local screenshot artifacts, stale admin workflow notes, and the remaining admin inline-handler budget.

Refactor Method

Use behavior-preserving vertical slices:

1. Pick one page type or component family.
2. Capture the current source, output, and expected behavior.
3. Move structure into data/template/module form.
4. Generate equivalent output.
5. Run checks and browser smoke tests.
6. Ratchet a budget only after the refactor is stable.

Current Engineering Pattern

The codebase now follows a clearer split between orchestration, rendering, and shared interaction primitives.

Build

• scripts/build-site.js is the build entrypoint and should stay mostly wiring.
• scripts/build/site-data.js owns source-data loading.
• scripts/build/dist.js owns final packaging into dist/.
• scripts/build/page-manifest.js owns route metadata and CSS bundle ownership.
• scripts/build/pipeline.js owns the build stage order.
• scripts/build/runtime-data-manifest.js owns cache-version metadata for static JSON.
• scripts/build/source-pages.js owns frontmatter parsing and source-page validation.

When adding build behavior, prefer a focused helper in scripts/build/ instead of growing the entrypoint.

Page Runtime

For larger interactive pages, prefer this shape:

• page coordinator: fetch/init/wire lifecycle
• render module: DOM rendering only
• content/config module: static question sets, labels, or mappings
• shared UI helper: repeated collection/sidebar interactions

Examples:

• books: js/books.js + js/books-view.js
• movies: js/letterboxd.js + js/letterboxd-render.js
• date funnel: js/dateme.js + js/dateme-content.js

Events

Prefer delegated data-action handlers over inline event attributes.

• js/action-dispatcher.js handles click, input, and submit
• js/collection-ui.js handles repeated collection behaviors like active state, expanding/collapsing groups, clear-button visibility, sidebar persistence, debounced inputs, and dropdown closing
• js/data-fetch.js handles version-aware fetches for static JSON so browser and CDN caching stay on while content changes still invalidate correctly

If a new page needs interaction wiring, start with delegated actions first and only add page-local listeners where delegation is awkward or stateful.

What Not To Do

• Do not hand-edit dist/.
• Do not rewrite all CSS or JS in one pass.
• Do not tighten CSP before inline handlers/scripts are removed.
• Do not introduce a heavy framework unless it clearly reduces total project complexity.
• Do not make visual “polish” changes inside an infrastructure refactor.