css/index.md at 03bc55dbea02e0d3555cf337cc641bb9e1966c0e

primer/css

mirror of https://github.com/primer/css.git synced 2024-12-03 03:33:40 +03:00

simurai 8cb9f2c4da Pin Primer CSS version

2021-03-12 22:08:41 +09:00

3.8 KiB

Raw Blame History

title	path
Getting started	getting-started/index

Primer CSS is open-sourced on GitHub and available on npm.

Installing via npm

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.

npm install @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.

@import '@primer/css/utilities/index.scss';
@import 'primer-buttons/index.scss';

// Import color variables for custom code
@import 'primer-support/index.scss';

// Override default blue
$blue: #0000ff;

@import './custom-that-uses-primer-variables.scss';

.foo {
  background: $blue;
  font-size: $h2-size;
  color: $text-gray;
}

Don't forget to add the compiled CSS to the <head> section of your page.

<link href="path/to/style.css" rel="stylesheet" />

Using Primer CSS on a static site

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:

<link href="https://unpkg.com/@primer/css@^16.0.0/dist/primer.css" rel="stylesheet" />

3.8 KiB Raw Blame History