Remove dist from tracking

[itsmedavep]

Goal

This branch changes the repository so packages/cfpb-design-system/dist/ is no longer tracked on main, while still allowing us to generate dist when we need it:

• locally during development
• when building and publishing the package
• when building and deploying the website

The branch achieves that by moving from a "commit built artifacts back to main" model to a "build artifacts from source when needed" model.

1: dist is now ignored

The branch adds packages/cfpb-design-system/dist/ to .gitignore.

That means:

• Generated package artifacts are now treated as build output
• Those artifacts no longer need to be committed to main
• Each workflow that needs them has to build them

2: Package generation

package.json now defines:

• yarn build-package
• yarn build

That means:

• yarn build-package
  • runs yarn tokens
  • then runs Vite with vite.config.packages.js
  • then writes `packages/cfpb-design-system/dist/index.(css and js)
• yarn bulid
  • runs yarn build-package
  • then runs the docs build with vite.config.packages.js

This is the important piece in the new approach. If dist is not tracked, yarn build-package becomes the way to create the package artifacts.

3: Local dev creates dist up front

yarn start now begins by running yarn build-package before it starts the local site/dev process

That is important because the docs site consumes dist directly. Without that upfront build the docs app could start against missing assets.

4: CI now validates builds instead of committing

.github.workflows.build.yml now does this on pushes and PRs against main:

• checks out the repo
• runs the shared setup
• runs yarn build
• runs bundle exec jekyll build

5: Pages deploy still rebuilds from source

.github/workflows/pages.yml calls ./scripts/update-gh-pages.sh.

That script:

1. checks out main
2. mounts gh-pages as a worktree
3. runs yarn install
4. runs yarn after-install
5. runs yarn build-decap
6. commits the generated site to gh-pages

yarn build-decap itself runs:

1. yarn install
2. yarn after-install
3. yarn build
4. bundle exec jekyll build

So the Pages flow still works without tracked package dist because it rebuilds all required assets from source before Jekyll output is published.

Notes

Why The Website Still Works

The website is not independent of package dist. It consumes it.

Examples:

• docs/assets/css/main.scss imports @cfpb/cfpb-design-system/dist/index.css
• docs/_layouts/default.html loads /dist/index.css and /dist/main.js
• docs/admin/index.html loads ../dist/admin-decap-cms.js

That means the website depends on two different generated artifact sets:

• package dist from yarn build-package
• docs dist from the docs Vite build

This new workflow is valid because yarn build produces both of those before Jekyll runs.

Package Publishing Still Works

The desired operating model is:

we will ALWAYS run yarn build-package to generate the package.

Under that assumption, the package path is works.

The relevant sequence is:

1. run yarn build-package
2. run the release flow
3. publish from packages/cfpb-design-system

scripts/release.sh already runs yarn build before npm publish, so the release flow still builds package artifacts before publishing.

The important behavior change is in team process:

• The build step must succeed every time because tracked artifacts are gone

Tokens And Generated Source Files

yarn build-package starts by running yarn tokens, which uses Style Dictionary and writes generated CSS under:

• packages/cfpb-design-system/src/elements/abstracts/
• packages/cfpb-design-system/src/elements/cfpb-button/

Those generated source CSS files are still tracked in git. They are separate from packages/cfpb-design-system/dist/.

So there are two different classes of generated output:

• tracked generated source artifacts
  • token-derived CSS in src/elements/...
• untracked generated distribution artifacts
  • bundled output in packages/cfpb-design-system/dist/

That matters because the branch stops tracking bundled dist, not every generated file in the repo.

What Now Becomes Critical

Because dist is no longer committed, a few commands become necessary infrastructure:

• yarn build-package
• yarn build
• yarn build-decap

If any of those fail, there is no committed dist on main to fall back to.

In practice that means:

• package releases depend on successful local generation
• local docs development depends on successful local generation
• CI depends on successful generation from a clean checkout
• Pages deploy depends on successful generation from a clean checkout

This is less forgiving of broken build steps than what we have today.

Wrap up

This branch does allow the project to stop tracking packages/cfpb-design-system/dist/ on main, while still generating dist when needed for local development, the website, and package creation.

The core idea is:

• do not store bundled artifacts in git
• always regenerate them from source in the workflow that needs them

The moving pieces that make that work are:

• .gitignore ignoring package dist
• yarn build-package as the accepted package artifact builder
• yarn build composing package and docs builds
• yarn start generating package artifacts before local docs work
• CI build checks proving artifacts can be rebuilt from source
• Pages deploy rebuilding the site from source before publishing

The only real DX requirement is that we continues treating yarn build-package and yarn build as mandatory build steps.

Changes

Testing

Screenshots

Before	After

Checklist

• PR has an informative and human-readable title
• Changes are limited to a single goal (no scope creep)
• Code can be automatically merged (no conflicts)
• Code follows the standards laid out in the CFPB development guidelines
• Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• Visually tested in supported browsers and devices (see checklist below 👇)
• Project documentation has been updated
• Reviewers requested with the Reviewers tool ➡️

Testing checklist

Browsers

Check the current browser support cutoff list for browsers that are advisable
to prioritize for testing.

Accessibility

• Keyboard friendly
• Screen reader friendly

Other

• Is useable without CSS
• Is useable without JS
• Flexible from small to large screens
• No linting errors or warnings
• JavaScript tests are passing