mirror of
https://github.com/primer/css.git
synced 2024-11-26 12:14:22 +03:00
ad358f2087
* upgrade * add all stories * new directory * move back to docs * remove from root * cleanup * try node 16 * adjust build script * try to fix build * try node 16 * maybe? * please * bye gatsby * fix button story * add info banner * add missing marketing docs
128 lines
4.7 KiB
Plaintext
128 lines
4.7 KiB
Plaintext
Primer CSS is [open-sourced on GitHub](https://github.com/primer/css) and [available on npm](https://www.npmjs.com/package/@primer/css).
|
|
|
|
## 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](https://docs.npmjs.com/getting-started/installing-node).
|
|
|
|
### 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](https://docs.npmjs.com/getting-started/using-a-package.json#creating-a-packagejson).
|
|
|
|
### 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.
|
|
|
|
```shell
|
|
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:
|
|
|
|
```scss
|
|
@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](https://jekyllrb.com/) version `3.3.1` or greater with:
|
|
|
|
```shell
|
|
jekyll -v
|
|
```
|
|
|
|
If you have an older version, follow the instructions in the [upgrading docs](https://jekyllrb.com/docs/upgrading/).
|
|
|
|
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.
|
|
|
|
```yml
|
|
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.
|
|
|
|
```scss
|
|
@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`.
|
|
|
|
```scss
|
|
@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.
|
|
|
|
```html
|
|
<link href="path/to/style.css" rel="stylesheet" />
|
|
```
|
|
|
|
### Troubleshooting Jekyll errors
|
|
|
|
Currently [jekyll-sass-converter](https://github.com/jekyll/jekyll-sass-converter) uses the [deprecated `LibSass` library](https://github.com/jekyll/jekyll-sass-converter#sass-implementations). Due to this you might run into issues. One way to deal with this is to use an experimental version of `jekyll-sass-converter` which uses [dart sass](https://sass-lang.com/dart-sass).
|
|
|
|
1. Add `jekyll-sass-converter` and `sass-embedded` to `Gemfile`:
|
|
|
|
```ruby
|
|
group :jekyll_plugins do
|
|
gem 'jekyll-sass-converter', github: 'jekyll/jekyll-sass-converter'
|
|
gem 'sass-embedded'
|
|
end
|
|
```
|
|
|
|
2. Run `bundle install`
|
|
|
|
```bash
|
|
$ bundle install
|
|
```
|
|
|
|
3. Update your `_config.yml`:
|
|
|
|
```yml
|
|
sass:
|
|
implementation: sass-embedded
|
|
```
|
|
|
|
Since GitHub pages is currently [locked to version `1.5.2` of `jekyll-sass-converter`](https://pages.github.com/versions/). If you run into errors you should look into [using the built CSS](#using-primer-css-on-a-static-site).
|
|
|
|
## 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](https://unpkg.com/@primer/css/dist/primer.css) from [unpkg.com](https://unpkg.com) and host it yourself. If that's not an option, you can include a CDN link in your HTML:
|
|
|
|
```html
|
|
<link href="https://unpkg.com/@primer/css@^20.2.4/dist/primer.css" rel="stylesheet" />
|
|
```
|