Source of Truth

The design system repo is the single source of truth for every shared token, class, and module. Consumer projects never own that code — they declare a version and receive the files. What that means in practice: why design-system.css sits in a consumer's folder but not its git history, what happens on every deploy, and how to preview an engine change before it ships.

Scope. This page describes projects that consume the design system — any product built on the engine. In the design system repo itself the relationship is inverted: assets/css/design-system.css is committed source, and dist/ is the gitignored build output the package ships from.

The Consumer Repo Stores the Claim, Not the Bytes

A consumer project records which version it wants. The files themselves arrive at install time and are never committed:

Delivered files carry a version stamp near the top:

/* @bydefaultstudio/design-system v2.1.0 */

The CSS and JS modules carry it on line 1. The sprites carry it below the XML declaration, DESIGN.md below its frontmatter, and the React adapters below their 'use client' directive — which has to stay the first statement — so search rather than assume a line number:

grep -m1 '@bydefaultstudio/design-system' assets/css/design-system.css

bd-sync prints the stamp it read back off disk at the end of every sync and warns when it disagrees with the version it installed. The CLI tools ship unstamped — a comment above the shebang would stop npx from running them. If a stamp and the lockfile disagree, run npm install; the delivered files are always disposable.

Icons travel the same path with one extra control: a project can trim the sprite to the icons it uses via icons.manifest.json — see the Iconography page.

Editing a Delivered File Cannot Stick

The vendored files exist on disk so the browser and your editor can read them, but git treats them as build output:

• They are recreated on demand. npm install fetches the declared version, and the project's own postinstall script (npx bd-sync) copies the stamped files into place. A project without that postinstall line installs the dependency and receives nothing — wiring it up is step one of consuming the package. Deleting the delivered files locally is harmless.
• Editing them is pointless. Any install — yours, a teammate's, a deploy — overwrites the file, and your edit vanishes without a trace. This is by design: it makes the wrong workflow impossible to sustain.
• Sync overlays; it does not sweep. A module the engine drops upstream lingers in the project until someone deletes it. After a major upgrade, clear the delivered directories and reinstall if something looks stale.
• Git history stays honest. A design system upgrade appears in a project as a one-line lockfile diff, not a ten-thousand-line CSS diff nobody reads.

Why the Rule Is Absolute

The rule reads as strict until you have seen what the alternative costs. Before the package existed, consumers vendored design system files directly and patched them in place whenever something needed to change locally. Two forks resulted: the studio site carried a CSS fork with its own local commits layered on top of the original, and Quiz forked bd-audio to add project-specific behaviour.

Neither fork was visible in day-to-day work. Nothing failed, nothing warned — until someone diffed the files against the source and found months of undocumented drift.

Upstream-first closes that gap: once a module ships in the package, it only changes in this repo. A consumer that needs different behaviour opens the request here rather than applying a local patch. Every consumer stays a straight line back to one source.

The Deploy Never Sees Your Machine

Every deploy assembles the design system files from the claim. The host never sees your local copies:

1. The build host clones the repo. At this point no design system CSS or JS exists in the tree — those files never travelled with git.
2. npm install runs. npm reads the dependency and fetches the declared version from the dist repo.
3. The project's postinstall runs bd-sync, which copies the stamped artifacts into place.
4. The project's build guard checks the delivered files landed. A failed fetch fails the build — the pipeline cannot publish an unstyled site behind a green status. Each consumer wires this check into its own build command; a stamp grep is enough.
5. The site publishes, design system included.

Because production always installs from the released package, nothing on your machine can leak into a deploy. Local experiments are invisible to the pipeline by construction.

An Upgrade Is a One-Line Diff

When 2.1.1 ships:

1. Run npm install in the project — or let Dependabot open the PR. The semver range (^2.1.0) already covers it.
2. The lockfile moves to the new version: a one-line diff.
3. Commit, push, deploy. The stamps in the CSS and JS read v2.1.1.

Pinned majors protect you from surprises: a breaking release (3.0.0) never arrives through ^2.x — upgrading across a major is a deliberate edit to package.json.

Wire up Dependabot and the upgrade arrives as a normal PR review on every new design-system-dist tag, instead of a manual check someone has to remember to run.

Companion Stylesheets

Some components ship a companion stylesheet alongside the core bundle instead of folding into it — dist/css/bd-cursor.css, dist/css/bd-video.css, and others as they land — so a consumer that doesn't use the component doesn't pay for its CSS.

Link the companion file after design-system.css, and after theme.css if the consumer has one.

Previewing an Engine Change Before It Ships

A shared component needs a fix and you want it on a real consumer before releasing. Do not edit the vendored file — edit upstream and sync the working tree in:

1. Make the change in the design system repo, in the actual source. It starts life where it will live.

2. In the consumer project, run:

   npx bd-sync --local <path-to-design-system-repo>
   

   The path defaults to ../Design System, the standard folder layout. This builds the package from the design system repo's working tree — uncommitted edits included — and copies the artifacts in exactly as a release would.

3. Refresh the local site and judge the change in context.

4. Iterate: edit upstream, re-run the sync, refresh.

5. When it's right: commit in the design system repo, roll it into the next release, then run a plain npm install in the project to return to released artifacts.

One catch: the working-tree build stamps with the version already in the design system repo's package.json, so a --local sync looks identical to the matching release. The stamp will not tell you that you are on unreleased bytes — bd-sync's summary line (source local working tree) will. Run a plain npm install before judging anything as shippable.

The consumer's git stays clean throughout — the synced files are ignored either way — and deploys keep installing the released version regardless of your local state.

Where Your Change Belongs

Before editing anything, decide which of these you are doing:

The one thing on no list: editing a vendored file. If the engine can't express what a project needs through tokens, that is a gap in the engine — fix it upstream, not around it.

The Theme Contract

The engine ships neutral tokens — no brand's colours, fonts, or voice baked in. A brand instance customises by overriding the Brand Tokens section of design-system.css in its own theme.css, loaded after the engine file.

By Default is instance #1: its identity lives in a theme.css like any other consumer. That is what keeps the engine/instance line real rather than aspirational — the engine cannot quietly acquire By Default's colours, because By Default gets them the same way a client does.