We recommend installing Primer CSS with npm: npm install --save @primer/css.
Before you start
Primer CSS requires npm version 3 or above. You can check which version you have by running npm -v. If you have a version that's older than 3.0, you can update it with npm install npm@latest -g. For more info, read the npm install docs.
Initialize npm project
Begin by initializing your project with a package.json file. You can read more on how to do this in the npm documentation.
Install Primer CSS
Install the Primer CSS npm package modules by running npm install @primer/css. This will install all of the SCSS source files into the node_modules/@primer/css directory.
npminstall @primer/css --save
Paths
Here's what you need to know about how the files are structured in both git and in the published npm module:
In git, all of the SCSS source files live in the src/ directory.
When published, all of the files in src/ are "hoisted" to the package root so that you can import, say, utilities with:
@import '@primer/css/utilities/index.scss';
All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with ../), so everything should work fine as long as the @primer/css directory is in one of your Sass include paths (i.e. node_modules).
For a Jekyll site
Make sure you have Jekyll version 3.3.1 or greater with:
jekyll -v
If you have an older version, follow the instructions in the upgrading docs.
Once you have Jekyll up and running, you will need to add this configuration to your _config.yml file. This let's the sass compiler know where your code lives.
sass:
# Where you keep your scss files
sass_dir: assets/css/
# Where sass should look for other scss
load_paths:
- node_modules/
It's best practice to import all of this scss into one file, usually named index.scss. From this file you'll import one or more Primer CSS bundles and any other custom code you write.
@import '@primer/css/core/index.scss';
// These files live in the same directory as the index file.
@import './custom-1.scss';
@import './custom-2.scss';
Here's an example of how it might look if you installed only a few Primer CSS components with some custom variable overrides. The $blue uses the default primer blue in the text utilities, then the new blue in "custom-that-uses-primer-variables.scss" and .foo.
You won't need to install any node modules or Sass compilers for a static site; you can use the built CSS. The best thing to do is to download the built CSS from the unpkg.com and host it yourself. If that's not an option, you can include a CDN link in your HTML: