Shipping a design system at ui.pangaea.id

ui.pangaea.id is the catalog for the Pangaea design system^ⓘ — where every UI component lives as a page you can browse, drive with controls, and copy the usage of. This is the story of how we pulled it out of one app, packaged it as versioned packages, published it to a registry, deployed the catalog to its own subdomain — and automated every component's release with Changesets^ⓘ.

Why we pulled the UI out

Every surface of pangaea.id grew from one rv-* system: color tokens, typography, and React components — but all of it was trapped inside one app. No other surface could use it without copy-paste. So the goal was clear: pull that system out into standalone, versioned, consumable primitives — so pangaea.id and future Pangaea surfaces draw from one shared source.

The catalog itself has a job: one place to browse each component, press-test every state (press the button, open the modal), and copy its exact usage. The right pane surfaces one control per prop, so you can turn a component into the shape you want, then copy the finished snippet.

One repo, many packages — the decision

There are three ways to package a set of components. We chose the third, and the reason matters.

The glue that makes it work is in every package.json: React is a peer dependency^ⓘ (not a plain dependency), so consumers never pull a second copy of React; each package ships its own CSS, precompiled from the --rv-* tokens; and all packages sit in one npm workspace^ⓘ so they link locally during development. The result: @labspangaea/ds-button can release to 0.1.2 while the other 36 packages stay at 0.1.0.

How the catalog deploys to ui.pangaea.id

The catalog is a static site (built by Astro). It compiles to a dist/ folder, then deploys to Cloudflare Pages^ⓘ — the exact same pipeline as pangaea.id itself. Only two parts are specific: creating the Pages project, then attaching the subdomain.

Step 1 — create the Pages project (once)

wrangler pages deploy does not auto-create the project; it errors Project not found. Create it once first, from the terminal:

npx wrangler login   # browser OAuth, one time
npx wrangler pages project create pangaea-ui --production-branch main

The name, pangaea-ui, must match --project-name in the deploy workflow exactly. After that every push to main builds the catalog and runs wrangler pages deploy apps/gallery/dist --project-name=pangaea-ui — live in seconds.

Step 2 — point the subdomain with a CNAME

The site is already live at pangaea-ui.pages.dev. To give it the pretty address ui.pangaea.id, add a custom domain to the Pages project, then one CNAME^ⓘ in DNS:

ui.pangaea.id   CNAME   pangaea-ui.pages.dev

Because pangaea.id's DNS is already on Cloudflare, adding the custom domain at Workers & Pages → pangaea-ui → Custom domains → ui.pangaea.id creates that CNAME record automatically and provisions its TLS certificate. Open ui.pangaea.id, and the catalog serves at the root.

Releasing a component — how Changesets works

This is the centerpiece. How a change to one button turns into a published 0.1.2 version, without you ever typing a version number by hand.

A changeset is one small .changeset/*.md file you commit alongside your change. It holds just two things: which package bumps and by how much (patch/minor/major), plus one changelog line.

---
"@labspangaea/ds-button": patch
---

Add a `loading` prop to Button.

From there, three commands do the rest — and you almost always only run the first:

• changeset — creates the .md file above (picks the package + size + summary).
• changeset version — applies all changesets: bumps the version in package.json, writes CHANGELOG.md, then deletes the consumed changeset files.
• changeset publish — publishes any package whose version isn't on the registry yet, and pushes its git tag.

The bump size follows semantic versioning^ⓘ: patch (0.1.0 → 0.1.1) for fixes, minor (0.1.0 → 0.2.0) for backward-compatible features, major (0.1.0 → 1.0.0) for breaking changes. Publishing targets GitHub Packages^ⓘ under the @labspangaea scope^ⓘ — which matches the repo owner, because that's what GitHub Packages requires.

The release pipeline, end to end

When a changeset lands on main, one CI/CD^ⓘ run does this whole chain itself:

From 2 PRs to 1

The first release took two manual merges. We fixed it to one. The difference is who merges the Version PR — you, or the bot.

The trick: a merge made by the built-in GITHUB_TOKEN does not trigger a new workflow run (GitHub blocks that to prevent a loop). So instead of waiting for the merge to trigger a publish, the workflow merges the Version PR and then publishes in the same run. No Personal Access Token, no second merge. The only manual step left in the whole release is writing the changeset.

What's next — moving www.pangaea.id onto the design system

The catalog at ui.pangaea.id is the packages' home; the next step is making www.pangaea.id consume them. apps/labs will add the @labspangaea/ds-* packages it uses, import them at build time, and vite-react-ssg prerenders them — so the HTML stays complete for crawlers, the CSP stays clean, and the deploy stays static (the SEO-safe model; no runtime fetch).

revamp.css is then progressively replaced by the CSS from @labspangaea/ds-tokens plus the components. Because the --rv-* token names are kept, the migration is mechanical: swap one component at a time, verify, move on. The system that was once trapped in a single app becomes the shared UI layer for every Pangaea surface — with www first.

The story behind the decision — the runtime module federation we nearly built and didn't — is in the build diary: The federation we didn't build.

Common questions

Sources

1. ui.pangaea.id — the Pangaea design system catalog
2. Changesets — per-package versioning + publishing
3. GitHub Packages — scoped npm registry
4. Cloudflare Pages — static site deploys