By Vamsi Krishna
Engineering · · Discuss

Starting point

A monorepo with ninety-three components, a gallery and a plain React consumer. Everything was tested and nothing was published.

Decisions along the way

  • Two packages. Contracts and state projection live in a framework-free core; React components sit on top.
  • Trusted publishing with a bootstrap token only for the first release of each package.
  • Alpha tag. Breaking changes are expected until 0.1.0.

What the first consumer broke

This site is the first consumer. Within a day it found three gaps:

  1. Button cannot render as a link. Every call to action on the site is a hand-styled anchor.
  2. Compound parts like Card.Header are undefined when imported into a Next.js Server Component, because static properties do not cross the client reference boundary.
  3. No chip, tag or avatar primitive, so filters, labels and bylines are custom CSS.
Dogfood before docs

A gallery shows that components render. Only a consumer shows whether the API is complete, so build the consumer first.

What ships next

alpha.2 adds a link button, a toggle group for filters, a neutral tag and flat exports for every compound part. The gaps list lives in the site repository.

Key takeaways

  • The first real consumer finds gaps no gallery does. Build the site with the library.
  • Compound components break across the server and client boundary. Export flat parts too.
  • Publish early with an alpha tag; the API feedback is worth the churn.