[RFC] Primer CSS package reorganization

[shawnbot]

📡 This is a request for comment! If you use Primer CSS, we'd love to hear from you in the comments.

TL;DR

Primer CSS can be a pain to use and maintain. To make things easier, we're moving all of the primer-* package source files into a new package called @primer/css and doing away with individually published packages.

The primer package will be unaffected by this change. Our next major release of Primer CSS will use a new @primer/css package name, and "legacy" Primer installations may continue to use the primer and primer-* packages until you're ready to upgrade them.

Motivations

1. Simplify use in Sass projects. Configuring Sass with the right include paths for an npm installation of primer and its sub-packages is tricky. Managing multiple "sub-packages" from the same "master" release of primer is also harder than it should be. Distributing a single package solves both of these problems.

2. Ease contribution and releasing. The monorepo setup is unwieldy and fragile. One package will be easier and quicker to run, test, and release. Adding a new component? Just make a directory! No need for a new package.json and cross-dependency version management.

3. Simplify documentation. Maintaining per-package READMEs and supplemental docs is painful, and we've twice now (with the Style Guide and the new docs site) built up relatively complex workflows for pulling disparate docs from each package into a site structure that we hope feels cohesive. Co-locating all of the docs under one directory should make this a lot easier.

4. Separate concerns. A slew of purpose-built scripts and tools have grown here to solve problems specific to our monorepo setup. Each of these tools needs to be tested and maintained, and doing so distracts us from the real work of improving Primer. Many will simply go away when we squash the monorepo; the rest should live elsewhere and be released separately.

5. Simplify refactoring. Making big changes (e.g. migrating from Sass to postcss) involves effectively refactoring dozens of individual codebases. Even workflow-related improvements are time-consuming because we have dozens of package.json files to update.

Upgrading

There will only be a handful of steps to migrate/upgrade once the new package is published:

1. Install the new @primer/css package
2. Replace the following path patterns in your SCSS imports:
   • primer/<path> → @primer/css/<path>
   • primer-<package>/<path> → @primer/css/<package>/<path>
3. Uninstall primer and/or any primer-* packages

This repo will be renamed from primer/primer to primer/css, so links should be updated. GitHub does a great job redirects for renamed repos, though, so it shouldn't be a problem if they're not.

We think this is going to dramatically simplify how we use, work on, and publish Primer CSS, and we're excited to get started.

🚀 ❤️ 🦄 ✨

[shawnbot]

This is happening in v12! See the tracking issue, #653, for more info.