Primer CSS Development
If you've made it this far, thank you! We appreciate your contribution, and hope that this document helps you along the way. If you have any questions or problems, don't hesitate to file an issue.
Primer CSS is published to npm as @primer/css. Each of Primer CSS's "modules" lives in a subfolder under
src/ with an
index.scss in it. Generally speaking, the styles are divided into three primary themes:
- Core styles (in
core/) are common dependencies, which include support variables, native element and typography styles, buttons, navigation, tooltips, etc.
- Product styles (in
product/) are specific to github.com, and include components such as avatars, labels, markdown styles, popovers, and progress indicators.
- Marketing styles (in
marketing/) are specific to GitHub marketing efforts, including international and event-focused sites as well as the more design-heavy feature pages on github.com. Marketing styles include new colors and button styles, and extend the core typography and whitespace scales.
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
When published, all of the files in
src/are "hoisted" to the package root so that you can import, say, utilities with:
All bundle interdependencies within Primer CSS are defined as relative imports (e.g. with
../), so everything should work fine as long as the
@primer/cssdirectory is in one of your Sass include paths (i.e.
The typical Primer workflow looks something like this:
npm installto install the development dependencies.
- Start Storybook
- Navigate to the module you're working on and modify the SCSS and/or markdown files.
- Test your changes in Storybook.
- Push your work to a new branch.
- Request a review from one of the Primer "core" team members.
npm install to install the npm dependencies.
Then visit http://localhost:3000/css to view the site.
http://localhost:3000/ if possible, as this may cause your development server to fail in less-than-graceful ways.
The pages directory
The pages directory contains all of the documentation files that map to URLs on the site. Because we host the site at
primer.style/css (and because of the way that Now's path aliasing feature works), we nest all of our documentation under the css subdirectory.
We have a script that catches inadvertent URL changes caused by renaming or deleting Markdown docs:
npm run test-urls
This script includes some exceptions for URLs that have been intentionally moved or removed in the process of moving away from the GitHub Style Guide, and which you will need to modify if you rename or remove either Markdown docs or their
path frontmatter. See #641 for more information.
Our Storybook setup allows you to view every HTML code block in Primer CSS's Markdown docs in isolation. To get started, run the Storybook server with:
npm run start-storybook
This should open up the site in your browser (if not, navigate to
html fenced code blocks in
src/**/*.md will be rendered as stories and listed under the relevant module's name in the left-hand nav. File changes should trigger a live reload automatically (after a brief delay).
Note: At this time, we do not load any stories from
script/dist, which creates CSS bundles of all the
check-linksruns a link checker on your local development server (
localhost:3000, started with
lintlints all of our SCSS source files.
lint-jslints the docs site and supporting scripts.
now-startare run on [Now] to build and start the docs site server.
now-testruns them both in order.
test-urlscompares a (pre-generated) list of paths from the Primer Style Guide to files in
pages/css, and lets us know if we've inadvertently deleted or renamed anything.
primer-migratecommand line utility.
watchruns the sync script in watch mode, copying files as they're changed from
You can list all of the available scripts with: