Sharing SCSS across projects

Reusing SCSS across sites: private npm packages, monorepos, and shared token files without copy-pasting _variables.scss into every repo.

When to extract

Share when two or more projects use the same tokens, mixins, or components and you are already syncing changes manually. Do not package too early – a folder copy is fine until the duplication hurts.

Package layout

@your-org/design-tokens/
  package.json
  scss/
    _index.scss
    _variables.scss
    _mixins.scss
  README.md

package.json names the package, sets main to scss/_index.scss, and lists scss in files so consumers install only what they need.

Barrel file forwards modules:

// scss/_index.scss
@forward 'variables';
@forward 'mixins';

Consuming in a project

npm install @your-org/design-tokens

// main.scss
@use '@your-org/design-tokens' as tokens;

.card {
  padding: tokens.$space-md;
}

Sass resolves packages from node_modules when configured. Some setups need loadPaths:

sass scss/main.scss css/main.css --load-path=node_modules

Versioning

Treat breaking token renames as semver major bumps. Document migration notes (‘$blue renamed to $color-brand‘). Consumers pin versions in package.json rather than floating to latest on every install.

Monorepo alternative

Multiple sites in one repo can @use '../shared/tokens' without publishing. Npm packages earn their keep when repos are separate or teams need independent release cycles.

Git dependency

Small teams sometimes install from Git with a dependency like github:your-org/design-tokens#v1.2.0.

Works, but npm registry or private Verdaccio is easier for caching and semver.

Try it

• Extract tokens and one mixin into a local folder outside your main SCSS tree.
• Consume them with @use and a load path.
• List what you would semver if this were a published package.