The document that overruled me
I shipped a change I liked, and a design constitution I’d ratified weeks earlier said no. Deciding who wins taught me what those documents are actually for.
Ever shipped something you liked on sight and regretted it by morning? Late June, mid redesign session, I flipped this site to dark mode by default. In the moment it was obviously right. The dark hero looked closest to the reference site whose composition I was porting, the light version read a little generic next to it, and the change was two small PRs. Merged, deployed, done.
The problem was a document I had written myself. Weeks earlier I’d ratified a visual constitution for this site, the kind of thing that sounds bureaucratic until you need it. Right there in section one, listed as an explicit non-goal: we are not pivoting to dark-mode-first. The whole identity is warm, light-primary, with dark as a respected guest. My taste at 11pm and my own ratified law were now in direct conflict, live, in production.
A constitution you edit whenever it disagrees with you is a mood board. So the real decision wasn’t dark versus light. It was comply versus amend. Amend was legitimately on the table; taste does shift, and the document has an amendment process that has been used since for other things. But one late-night reaction to one hero section is not a shift in direction. It’s a mood. I chose comply and reverted to system preference the next day.
Salvage before you revert
The revert had one subtlety worth stealing. The wrong turn had produced two genuinely good pieces of engineering: a pre-paint script that kills the theme flash on first load, and a fix for a stale color-scheme property on runtime toggles. The revert kept both and dropped only the default flip. Going back doesn’t mean pretending the trip taught you nothing.
The constitution’s answer for what I was actually chasing turned out to be better than my shortcut, too. The gap I felt was real, but the document prescribed deepening the light mode’s atmosphere instead of abandoning it, and that work made the light theme the stronger of the two. The law knew what I wanted better than I did that night.