Margin Notes

The design-system docs at Squarespace, like every design-system docs site ever made, were always a little bit wrong.

Margin Notes was the obvious answer: let people leave comments. A reviewer flags a stale code sample. A designer notes that the component's padding doesn't match Figma. The library maintainer sees the comment and fixes the docs. Loop closes; everyone's a little less miserable. It shipped in October 2020 and was used immediately by the entire design-systems guild.

For about three months it was the best thing in the building.

The problem with annotation tools is they treat the symptom. If your docs need three hundred annotations to be trusted, you do not have an annotations problem; you have a docs problem. The comments piled up. The fixes lagged behind. After six months Margin Notes had become a list of complaints with a half-life of forever — a public-facing reminder that nobody owned the docs hard enough to rewrite them.

The right solve, looking back, was to halve the docs and double the editorial standard for the rest. Margin Notes let us avoid that conversation for a year. The tool worked. The thing the tool was for didn't.