13 KiB
16.0.0
In v16 three major changes happened:
- All colors got moved to primer/primitives. This lets us use the same Primer colors across different libraries.
- The naming of the variables changed from presentational to functional names, like
text-gray-darkbecametext-primaryso that they still make sense in different color modes. - Primer CSS switched from using SASS variables to CSS variables (for now only colors). By using CSS variables, components and utility classes can now switch between different color modes at runtime.
Below a migration guide when updating Primer CSS to 16.0.0:
Components
Most components don't need to be updated and should work without making changes. But some of the componets that use presentational class names now use functional class names.
Labels
v15 |
v16 |
|---|---|
.Label--gray-darker |
.Label--primary |
.Label--gray |
.Label--secondary |
.Label--blue |
.Label--info |
.Label--green |
.Label--success |
.Label--yellow |
.Label--warning |
.Label--red |
.Label--danger |
.Label--orange |
n/a |
.Label--purple |
n/a |
.Label--pink |
n/a |
Counters
v15 |
v16 |
|---|---|
.Counter--gray |
.Counter--primary |
.Counter--gray-light |
.Counter--secondary |
States
v15 |
v16 |
|---|---|
| n/a | .State--draft |
.State--green |
.State--open |
.State--purple |
.State--merged |
.State--red |
.State--closed |
Utility classes
Text
v15 |
v16 |
|---|---|
.text-gray-dark |
.color-text-primary |
.text-gray |
.color-text-secondary |
.text-gray-light |
.color-text-tertiary |
.text-blue |
.color-text-link |
.text-green |
.color-text-success |
.text-yellow |
.color-text-warning |
.text-red |
.color-text-danger |
.text-white |
.color-text-inverse |
.text-black |
n/a |
.text-orange |
n/a |
.text-orange-light |
n/a |
.text-purple |
n/a |
.text-pink |
n/a |
Icon
v15 |
v16 |
|---|---|
| n/a | .color-icon-primary |
| n/a | .color-icon-secondary |
| n/a | .color-icon-tertiary |
| n/a | .color-icon-info |
| n/a | .color-icon-success |
| n/a | .color-icon-warning |
| n/a | .color-icon-danger |
Border
v15 |
v16 |
|---|---|
.border-gray |
.color-border-primary |
.border-gray-light |
.color-border-secondary |
.border-gray-dark |
.color-border-tertiary |
.border-blue |
.color-border-info |
.border-green |
.color-border-success |
.border-yellow |
.color-border-warning |
.border-red |
.color-border-danger |
.border-white |
.color-border-inverse |
.border-gray-darker |
n/a |
.border-blue-light |
n/a |
.border-red-light |
n/a |
.border-purple |
n/a |
.border-black-fade |
n/a |
.border-white-fade |
n/a |
.border-white-fade-15 |
n/a |
.border-white-fade-30 |
n/a |
.border-white-fade-50 |
n/a |
.border-white-fade-70 |
n/a |
.border-white-fade-85 |
n/a |
Background
v15 |
v16 |
|---|---|
.bg-white |
.color-bg-primary |
.bg-gray-light |
.color-bg-secondary |
.bg-gray |
.color-bg-tertiary |
.bg-gray-dark |
.color-bg-canvas-inverse |
.bg-blue-light |
.color-bg-info |
.bg-blue |
.color-bg-info-inverse |
.bg-green-light |
.color-bg-success |
.bg-green |
.color-bg-success-inverse |
.bg-yellow-light |
.color-bg-warning |
.bg-yellow |
.color-bg-warning-inverse |
.bg-red-light |
.color-bg-danger |
.bg-red |
.color-bg-danger-inverse |
| n/a | .color-bg-canvas |
.bg-purple-light |
n/a |
.bg-purple |
n/a |
.bg-yellow-dark |
n/a |
.bg-orange |
n/a |
.bg-pink |
n/a |
Shadow
v15 |
v16 |
|---|---|
.box-shadow |
.color-shadow-small |
.box-shadow-medium |
.color-shadow-medium |
.box-shadow-large |
.color-shadow-large |
.box-shadow-extra-large |
.color-shadow-extra-large |
Link
The link utilities are part of the Link component.
v15 |
v16 |
|---|---|
.link-gray-dark |
.Link--primary |
.link-gray |
.Link--secondary |
.muted-link |
.Link--muted |
.link-hover-blue |
.Link--onHover |
| n/a | .Link |
Variables
Text
v15 |
v16 |
|---|---|
$text-gray-dark ($gray-900) |
var(--color-text-primary) |
$text-gray ($gray-600) |
var(--color-text-secondary) |
$text-gray-light ($gray-500) |
var(--color-text-tertiary) |
$text-white ($white) |
var(--color-text-inverse) |
$text-blue ($blue-500) |
var(--color-text-link) |
$text-green ($green-600) |
var(--color-text-success) |
$text-red ($red-600) |
var(--color-text-danger) |
$text-yellow ($yellow-800) |
var(--color-text-warning) |
| n/a | var(--color-text-placeholder) |
| n/a | var(--color-text-disabled) |
$text-black ($black) |
n/a |
$text-orange ($orange-900) |
n/a |
$text-orange-light ($orange-600) |
n/a |
$text-purple ($purple-500) |
n/a |
$text-pink ($pink-500) |
n/a |
Icon
v15 |
v16 |
|---|---|
| n/a | var(--color-icon-primary) |
| n/a | var(--color-icon-secondary) |
| n/a | var(--color-icon-tertiary) |
| n/a | var(--color-icon-info) |
| n/a | var(--color-icon-danger) |
| n/a | var(--color-icon-success) |
| n/a | var(--color-icon-warning) |
Border
v15 |
v16 |
|---|---|
$border-color ($gray-200) |
var(--color-border-primary) |
$border-gray ($gray-200) |
var(--color-border-primary) |
$border-gray-light (lighten($gray-200, 3%)) |
var(--color-border-secondary) |
$border-gray-dark ($gray-300) |
var(--color-border-tertiary) |
$border-white ($white) |
var(--color-border-inverse) |
$border-blue ($blue-500) |
var(--color-border-info) |
$border-green ($green-400) |
var(--color-border-success) |
$border-red ($red-500) |
var(--color-border-danger) |
$border-yellow ($yellow-600) |
var(--color-border-warning) |
$border-gray-darker ($gray-700) |
n/a |
$border-blue-light ($blue-200) |
n/a |
$border-red-light ($red-300) |
n/a |
$border-purple ($purple-500) |
n/a |
$border-black-fade ($black-fade-15) |
n/a |
$border-white-fade ($white-fade-15) |
n/a |
$border-green-light (desaturate($green-300, 40%)) |
n/a |
Background
v15 |
v16 |
|---|---|
$bg-white ($white) |
var(--color-bg-primary) |
$bg-gray-light ($gray-000) |
var(--color-bg-secondary) |
$bg-gray ($gray-100) |
var(--color-bg-tertiary) |
$bg-gray-dark ($gray-900) |
var(--color-bg-canvas-inverse) |
$bg-red ($red-500) |
var(--color-bg-danger-inverse) |
$bg-red-light ($red-000) |
var(--color-bg-danger) |
$bg-green ($green-500) |
var(--color-bg-success-inverse) |
$bg-green-light ($green-100) |
var(--color-bg-success) |
$bg-blue ($blue-500) |
var(--color-bg-info-inverse) |
$bg-blue-light ($blue-000) |
var(--color-bg-info) |
$bg-yellow ($yellow-500) |
var(--color-bg-warning-inverse) |
$bg-yellow-light ($yellow-200) |
var(--color-bg-warning) |
| n/a | var(--color-bg-canvas) |
$bg-black ($black) |
n/a |
$bg-black-fade ($black-fade-50) |
n/a |
$bg-orange ($orange-700) |
n/a |
$bg-purple ($purple-500) |
n/a |
$bg-purple-light ($purple-000) |
n/a |
$bg-pink ($pink-500) |
n/a |
$bg-yellow-dark ($yellow-700) |
n/a |
Shadow
v15 |
v16 |
|---|---|
$box-shadow |
var(--color-shadow-small) |
$box-shadow-medium |
var(--color-shadow-medium) |
$box-shadow-large |
var(--color-shadow-large) |
$box-shadow-extra-large |
var(--color-shadow-extra-large) |
$box-shadow-highlight |
var(--color-shadow-highlight) |
$box-shadow-inset |
var(--color-shadow-inset) |
$box-shadow-focus |
var(--color-state-focus-shadow) |
Color System
v15 |
v16 |
|---|---|
$black |
var(--color-scale-black) |
$white |
var(--color-scale-white) |
$gray-000 |
var(--color-scale-gray-0) |
$gray-100 |
var(--color-scale-gray-1) |
$gray-200 |
var(--color-scale-gray-2) |
| ... | ... |
$pink-700 |
var(--color-scale-pink-7) |
$pink-800 |
var(--color-scale-pink-8) |
$pink-900 |
var(--color-scale-pink-9) |
Happy migrating!
12.0.0
The v12 release marks a major transition from small, single-purpose npm packages (primer-core, primer-marketing, primer-utilities, etc.) to a single package — @primer/css — which contains all of the SCSS source files in subdirectories. Here's what you need to do to migrate different parts of your app:
npm
First, install the new package.
npm install --save @primer/css
If you use the primer package, all you'll need to do is:
npm uninstall --save primer
If you use other packages, such as primer-utilities, you will need to uninstall each one by name or use a command line tool like jq to list them:
jq -r '.dependencies | keys[] | select(.|startswith("primer"))' package.json
And, if you're feeling saucy, uninstall them all by piping that to xargs npm uninstall. ✨
Sass
There are a couple of things you'll need to change in your Sass setup when migrating to v12. This section is intentionally vague because environments vary wildly between text editors, Sass implementations, and application frameworks. When in doubt, consult the relevant documentation, and feel free to file an issue if you think that we can help.
Sass imports
Generally speaking, all of your Sass @import statements can be migrated with the following search-and-replace operations, in the following order:
- If you import
primer/index.scssorprimer, just replaceprimerwith@primer/cssand you're done! - Otherwise...
- Replace
primer-marketing-with@primer/css/marketing/, e.g.primer-marketing-buttons/index.scssbecomes@primer/css/marketing/buttons/index.scssprimer-marketing-utilities/index.scssbecomes@primer/css/marketing/utilities/index.scss
- Replace
primer-with@primer/css/, e.g.primer-markdown/index.scssbecomes@primer/css/markdown/index.scssprimer-utilities/index.scssbecomes@primer/css/utilities/index.scss
- Delete
lib/from every Primer CSS path, e.g.primer-forms/lib/form-control.scssbecomes@primer/css/forms/form-control.scssprimer-navigation/lib/subnav.scssbecomes@primer/css/navigation/subnav.scss
- Replace
If your text editor supports search and replace regular expressions, the following patterns should work:
| find | replace |
|---|---|
primer-marketing-(\w+)(\/lib)? |
@primer/css/marketing/$1 |
primer-(\w+)(\/lib)? |
@primer/css/$1 |
primer\b |
@primer/css |
primer-migrate
You can also use the included primer-migrate script:
npx -p @primer/css primer-migrate path/to/**/*.scss
Sass include paths
If you've installed Primer CSS with npm, you very likely already have node_modules listed in your Sass includePaths option, and you won't need to change anything. 🎉
If you've installed Primer CSS with something other than npm, or you don't know how it was installed, consult the documentation for your setup first, then let us know if you still can't figure it out.
Compiled CSS files
The compiled CSS files can be found under /dist in case you want to directly link to them.
Fonts
The marketing-specific font files published in the fonts directory of primer-marketing-support@2.0.0 are published in the fonts directory of @primer/css. If you use these fonts, you'll need to do the following:
- Update any scripts that copy the
.wofffont files fromnode_modules/primer-marketing-support/fontsinto your application to look for them innode_modules/@primer/css/fonts. - Update any webpack (or other bundler) resolution rules that look for fonts in
primer-marketing-support/fontsto look for them in@primer/css/fonts. - Customize the
$marketing-font-pathvariable to match the path from which they're served.