Paperclip CMS

01 // The brief

“We need a component library”

Paperclip is a content platform with four product squads that grew apart over five years. The inventory from week one: eleven button implementations, three modal systems, two date pickers that disagreed about time zones, and eleven hex values all described internally as “our blue”.

Two previous attempts at a shared library existed in the monorepo. Both were technically fine. Both had been abandoned within a quarter because nothing obliged anyone to use them.

02 // The constraint

Nobody would accept a roadmap freeze

All four squads had committed quarterly goals. A migration that required stopping feature work was never going to be approved, so the system had to be adoptable one component at a time, in production, alongside the old code.

The third attempt succeeded because it changed the incentives, not because the code was better than the first two.

03 // What shipped

Governance first, then components

1. A three-tier token architecture. Primitives (blue-600) feed semantic tokens (action-primary) feed component tokens (button-bg-rest). Product code may only reference the semantic tier, enforced by a lint rule.
2. A written decision rule. One page: who may add a component, what evidence is required, and the escalation path. Signed by all four leads before any code was written. This was the whole ballgame.
3. Codemods, not tickets. Each component shipped with a codemod that migrated call sites automatically. Squads got a pull request rather than a backlog item, which is the difference between adoption and intention.
4. Visual regression in CI. 340 snapshots across light, dark, and forced-colours modes. A token change now shows you every screen it touches before merge.
5. A public changelog with deprecation dates. Old components log a console warning naming the removal date and the replacement. Nothing was ever deleted by surprise.

           w1   w3   w5   w7   w9   w11
  squad A   ▁    ▃    ▅    ▆    ▇    █   98%
  squad B   ▁    ▂    ▄    ▆    ▇    █   99%
  squad C   ▁    ▁    ▂    ▄    ▆    ▇   91%
  squad D   ▁    ▂    ▃    ▅    ▇    █   96%
           ---------------------------------
  system    ▁    ▂    ▄    ▅    ▇    █   96%
          

04 // The result

Squad C is the interesting one

Three squads crossed 95% adoption by week eleven. Squad C stalled at 91% and stayed there, because their editor surface genuinely needs a different interaction model. That is not a failure — the decision rule has a documented exemption path, and they used it. A system that cannot say “not here” gets worked around instead.

Across the platform, CSS shipped dropped 38% and the median time from design handoff to production fell from 12 days to 3.5.

client

“Handover is where contractors usually vanish. We got documentation, a recorded walkthrough, and a week of pairing. Six months on, my team is still shipping with the system unaided.”

05 // What I would do differently

I built the date picker too early

It was the loudest request, so it went second. It should have gone last: it took three weeks, it blocked nobody, and shipping four trivial components in that time would have built momentum faster. Order components by how much duplication they remove, not by how loudly they are requested.