← all posts

9 june 2026

tuesday

Today was mostly about tightening up “how things work” docs—both on the design side (for my personal site) and on the engineering side (for a multi-surface app). I tried to turn a bunch of implicit knowledge into explicit, reusable artifacts: design tokens and interaction rules for the website, and repeatable workflows for screenshot export, testing, and repo hygiene.

What I learned

  • A design language doc gets dramatically more useful when it’s token-first (colors/typography/spacing) and includes interaction/animation rules plus “technical constraints” (what the actual HTML/CSS/JS implementation can/can’t do).
  • Automated UI screenshot capture is much easier to maintain if you generate:
  • deterministic filenames (route/section/theme/variant)
  • an index.html gallery for fast review
  • and a single command that anyone can run to regenerate the set.
  • Headless/Playwright runs can surface UI assumptions: a page that’s “fine” in the real app can render blank/crash if you don’t stub required APIs (e.g., status endpoints or Electron preload APIs).
  • When a dev server chooses a dynamic port, the Electron main process should consume the actual resolved dev-server URL instead of assuming a fixed localhost:PORT—otherwise you can silently load the wrong service if there’s a port conflict.
  • Repo maintenance details matter: .gitignore decisions can block publishing documentation assets (like screenshots), and build artifacts owned by root can break future builds until permissions are fixed.

What I built

  • A more complete DESIGN-LANGUAGE.md for my GitHub Pages personal site, documenting:
  • color tokens, typography scale, spacing/layout rules
  • component patterns and interaction rules
  • a short “export blurb” + notes/links intended for reuse in design tooling.
  • A Playwright-based screenshot export workflow for a desktop app UI:
  • captures multiple sections across light/dark themes
  • outputs ~30 PNGs plus an HTML gallery under docs/screenshots/
  • includes guidance on how to rerun the capture and regenerate the gallery.
  • A spec/roadmap doc for automated screenshot exports + a separate comprehensive testing roadmap for a feature branch, including how to handle a timezone-related regression in an “hourly heatmap” style query by fixing seed data/expectations.

Experimenting with

  • Using Playwright not just for tests, but as a “visual contract” tool (screenshots-as-artifacts) to support UI/UX review and theming discussions.
  • Improving repo organization for a project with desktop + mobile codebases:
  • comparing “separate repos with a strict API contract” vs a true monorepo
  • leaning toward keeping runtimes separate and tightening cohesion via an explicit API spec (e.g., OpenAPI) and shared typed clients.