Design writeup
One owner for every write
How one module now owns theme updates from the editor, assistant, shared URLs, and storage, including validation, identity, and targeted DOM writes.
ArchitectureDeep modulesState designTesting
ReadEngineering notes
Engineering decisions, with the reasoning behind them.
Notes from building this site: architecture decisions, performance measurements, and later writeups about the theme system. Each explains the problem, tradeoffs, and what I would revisit.
Decision record
The anti-FOUC script must be generated, not hand-written
The first-paint theme fix is deferred. When implemented, its script must be generated from the Active Theme module to avoid duplicating validation and CSS-variable mappings.
ADRDeferred workDuplication
ReadDecision record
Theme identity is determined by history, not by value
A theme edited away from a preset stays custom, even if its values later match. This decision avoids comparing every value against every preset during each colour drag.
ADRIdentityTradeoffs
ReadDecision record
Invalid theme values are clamped silently
The editor and AI assistant share one validation policy. The note also corrects its original description of the code's behavior before that policy was implemented.
ADRValidationAI safetyHonest documentation
ReadMeasurement
Theme updates: performance baseline
A radius edit went from 54 CSS-variable writes to 1. This note records the measurements, their limits, and the unit tests that now check which variables each operation returns.
PerformanceMeasurementRegression testing
Read