diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 85bb548261..13c3fccb64 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -50,17 +50,17 @@ Good pull requests—patches, improvements, new features—are a fantastic help. **Please ask first** before embarking on any significant pull request (e.g. implementing features, refactoring code, porting to a different language), otherwise you risk spending a lot of time working on something that the project's developers might not want to merge into the project. -### Updating Primer modules +### Updating Primer CSS modules -Anyone can open a pull request on Primer. You do not need to work at GitHub or be a member of the org to open a pull request. +Anyone can open a pull request on Primer CSS. You do not need to work at GitHub or be a member of the org to open a pull request. -1. Fork and clone [this repository](https://github.com/primer/primer). +1. Fork and clone [this repository](https://github.com/primer/css). 2. Configure and install the dependencies: `npm install` 3. Create a new branch from master `git checkout -b my-branch-name` 4. Make your changes and commit them. 5. Push your branch and open a pull request. Add a comment describing your proposed changes and request a review from `@primer/ds-core`. 6. Wait for CI tests to finish. - - If the tests pass, you should see a status check telling you which alpha version of primer you can install with npm to test your work in other projects. + - If the tests pass, you should see a status check telling you which alpha version of `@primer/css` you can install with npm to test your work in other projects. - If the tests fail, review the logs and address any issues. - If the builds fail for any other reason (as they occasionally do), they may need to be manually restarted. 7. When CI tests pass, a new npm alpha release will be posted under the CI checks, you can use this npm version for testing in your project or with a GitHub site if you are staff. @@ -71,7 +71,7 @@ Here are a few things you can do that will increase the likelihood of your pull - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. - Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). -## Releasing a new Primer version +## Releasing a new Primer CSS version See [RELEASING.md](../RELEASING.md) for our release process. ## Resources @@ -80,6 +80,6 @@ See [RELEASING.md](../RELEASING.md) for our release process. - [Using Pull Requests](https://help.github.com/articles/using-pull-requests/) - [GitHub Help](https://help.github.com) -[fork]: https://github.com/primer/primer/fork -[pr]: https://github.com/primer/primer/compare -[style]: https://styleguide.github.com/primer/principles/ +[fork]: https://github.com/primer/css/fork +[pr]: https://github.com/primer/css/compare +[style]: https://primer.style/css/principles diff --git a/.github/ISSUE_TEMPLATE/primer-bug-report.md b/.github/ISSUE_TEMPLATE/primer-bug-report.md index 2c2c622ea4..4989b09c2e 100644 --- a/.github/ISSUE_TEMPLATE/primer-bug-report.md +++ b/.github/ISSUE_TEMPLATE/primer-bug-report.md @@ -1,6 +1,6 @@ --- -name: Primer bug report -about: Create a report to help us improve primer +name: Primer CSS bug report +about: Create a report to help us improve Primer CSS --- diff --git a/.github/ISSUE_TEMPLATE/primer-feature-request.md b/.github/ISSUE_TEMPLATE/primer-feature-request.md index 3f2aba7814..91b0ec32d5 100644 --- a/.github/ISSUE_TEMPLATE/primer-feature-request.md +++ b/.github/ISSUE_TEMPLATE/primer-feature-request.md @@ -1,5 +1,5 @@ --- -name: Primer feature request +name: Primer CSS feature request about: Suggest an idea for this project --- diff --git a/DEVELOP.md b/DEVELOP.md index 55a473413c..d91a5c00d0 100644 --- a/DEVELOP.md +++ b/DEVELOP.md @@ -1,4 +1,4 @@ -# Primer Development +# 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](https://github.com/primer/css/issues/new). @@ -60,23 +60,13 @@ If, for whatever reason, the dev server isn't syncing files from `src/` to `page script/sync ``` - **If you find yourself needing to do this often, please [file an issue](/primer/primer/issues/new) and tag `@shawnbot`**. :bow: + **If you find yourself needing to do this often, please [file an issue](/primer/css/issues/new) and tag `@shawnbot`**. :bow: ### The pages directory -The [pages directory](./pages/) contains all of the files that map to URLs on the site. Because we plan to 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](./pages/css). +The [pages directory](./pages/) contains all of the 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](./pages/css). The sync task maintains a list of files copied from `src/` in `pages/css/.gitignore`, which ensures that none of these generated files are checked into git. -### Sync internals -We use [Metalsmith] to sync the source docs to the `pages` directory and transform them in the following ways: - -1. We filter the list of files to only Markdown documents (`**/*.md`). -1. Many bundle `README.md`s wrap the actual documentation content in `` HTML comments that usually include YAML frontmatter. In these instances, we extract the content that portion and reformat the frontmatter. -1. We filter out any Markdown files that _don't_ include a `path` frontmatter key, and rename the destination file to match the `path` (e.g. `path: foo/bar` writes to `pages/css/foo/bar.md`). -1. We set the `source` frontmatter key to a fully-qualified `github.com` URL for the source file so that we can link directly to it. -1. We read the list of files from `pages/css/.gitignore` and delete them from the filesystem, then write the new list of paths so that they aren't committed to git. - -All of the logic for syncing the source docs (and transforming them in transit) is controlled in [`lib/sync.js`](./lib/sync.js), and each "step" in the transformation (as well as the watching) is implemented as a Metalsmith plugin. ### URL tests We have a script that catches inadvertent URL changes caused by renaming or deleting Markdown docs: @@ -124,7 +114,6 @@ npm run [@primer/css]: https://www.npmjs.com/package/@primer/css -[metalsmith]: https://metalsmith.io/ [run-scripts]: https://docs.npmjs.com/cli/run-script [storybook]: https://storybook.js.org/ [npm]: https://www.npmjs.com/ diff --git a/RELEASING.md b/RELEASING.md index aa01e2c58f..065cb32b01 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -12,7 +12,7 @@ 1. Create a new PR for the `release-` branch. Please use the following template for the PR description, linking to the relevant issues and/or pull requests for each change, removing irrelevant headings and checking off all of the boxes of the ship checklist: ```md - # Primer [Major|Minor|Patch] Release + # Primer CSS [Major|Minor|Patch] Release Version: 📦 **0.0.0** Approximate release date: 📆 DD/MM/YY @@ -71,7 +71,7 @@ Then commit and push the changes to `package.json`, `package-lock.json`, `LICENSE` and `vendor/npm`. -1. If you need to make changes to github/github due to the Primer release, do them in a branch and merge _that_ into your release branch after testing. +1. If you need to make changes to github/github due to the Primer CSS release, do them in a branch and merge _that_ into your release branch after testing. 1. Add or re-request reviewers and fix any breaking tests. @@ -106,5 +106,14 @@ 1. Deploy! :rocket: +### Publish the release + +1. [Create a new release](https://github.com/primer/css/releases/new) with tag `v`. + +2. Copy the changes from the [CHANGELOG] and paste them into the release notes. + +3. Publish 🎉 + + [changelog]: ../CHANGELOG.md [primer/publish]: https://github.com/primer/publish diff --git a/pages/css/components/forms.md b/pages/css/components/forms.md index 25fee25fc9..19c3d4de03 100644 --- a/pages/css/components/forms.md +++ b/pages/css/components/forms.md @@ -50,7 +50,7 @@ All our inputs and buttons side-by-side for easy testing of sizing and alignment #### Example form -Form controls in Primer currently have no basic layout specified (this is by design). You'll need to use `
`s, `
`s, or other elements and styles to rearrange them. +Form controls in Primer CSS currently have no basic layout specified (this is by design). You'll need to use `
`s, `
`s, or other elements and styles to rearrange them. ```html
@@ -125,7 +125,7 @@ Webkit sometimes gets confused and tries to add an icon/dropdown to autofill con #### Selects -Primer adds light `height` and `vertical-align` styles to ``s for all browsers to render them consistently with textual inputs. ```html diff --git a/pages/css/components/navigation.md b/pages/css/components/navigation.md index 935b4aae51..1ffac7f798 100644 --- a/pages/css/components/navigation.md +++ b/pages/css/components/navigation.md @@ -7,7 +7,7 @@ bundle: navigation --- -Primer comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently. +Primer CSS comes with several navigation components. Some were designed with singular purposes, while others were design to be more flexible and appear quite frequently. {:toc} @@ -317,5 +317,3 @@ You can also use a `subnav-search-context` to display search help in a select me
``` - - diff --git a/pages/css/getting-started/contributing.md b/pages/css/getting-started/contributing.md index 1bda29a40c..7338ea41b9 100644 --- a/pages/css/getting-started/contributing.md +++ b/pages/css/getting-started/contributing.md @@ -8,7 +8,7 @@ Guidelines for contributing to GitHub's CSS. - [Decision process for adding new styles](#decision-process-for-adding-new-styles) - [Step-by-step instructions for adding new styles](#step-by-step-instructions-for-adding-new-styles) - [Documentation structure](#documentation-structure) -- [Primer modules](#primer-modules) +- [Primer CSS modules](#primer-css-modules) - [Ship checklist](#ship-checklist) ## Decision process for adding new styles @@ -72,7 +72,7 @@ Let the [design systems team](https://github.com/github/design-systems) know if ## Documentation structure -_**Note:** Documentation for Primer modules should live in the `README` of that module, see the [primer modules](#primer-modules) section below for more details. The [anatomy of a guide](#anatomy-of-a-guide) will work the same as part of a module README as well as regular markdown documentation._ +_**Note:** Documentation for Primer CSS modules should live in the `README` of that module, see the [primer modules](#primer-modules) section below for more details. The [anatomy of a guide](#anatomy-of-a-guide) will work the same as part of a module README as well as regular markdown documentation._ The style guide takes a content first approach. Everything you see on the site is built from markdown files found in this folder. @@ -171,7 +171,7 @@ When using code blocks for demo purposes, you can choose to render each of the b ``` ``` -## Primer modules +## Primer CSS modules Modules are created for all the styles we include in the Primer framework. Modules are folders with a specific structure that include CSS, a `package.json`, and other files for publishing to repositories in our GitHub Primer organization and NPM. @@ -250,6 +250,6 @@ To publish, there are two requirements. First, you must be on the `master` branc #### Versioning -All the individual Primer modules are [semver](http://semver.org/) versioned. This helps others know when a change is a patch, minor, or breaking change. +Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change. To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so I recommend reviewing [semver](http://semver.org/) and/or ask in [#design-systems](https://github.slack.com/archives/design-systems) or and experienced open-source contributor. diff --git a/pages/css/getting-started/index.md b/pages/css/getting-started/index.md index fe8dacffd3..a622c72c6a 100644 --- a/pages/css/getting-started/index.md +++ b/pages/css/getting-started/index.md @@ -3,26 +3,26 @@ title: Getting started path: getting-started/index --- -Our CSS framework, Primer, is [open-sourced on GitHub](https://github.com/primer/primer) and [hosted on npm](https://www.npmjs.com/package/primer). Our modules are grouped into three packages: [primer-core](https://github.com/primer/primer/tree/master/modules/primer-core), [primer-product](https://github.com/primer/primer/tree/master/modules/primer-product), and [primer-marketing](https://github.com/primer/primer/tree/master/modules/primer-marketing). `primer-core` contains packages used in both product (github.com) and marketing (logged out homepage). To install all of primer, you can use [primer](https://github.com/primer/primer) which is a grouping of core, product and marketing. +Primer CSS is [open-sourced on GitHub](https://github.com/primer/primer) and [available on npm](https://www.npmjs.com/package/primer). ## Installing via npm -We recommend using npm to install primer because of how easy npm is for managing dependencies. +We recommend installing Primer CSS with npm: `npm install --save @primer/css`. ### Before you start -Primer packages require npm version 3 or above. You can check what version you have by running `npm -v`. If you have a version that's older than 3.0, you can update it by running `npm install npm@latest -g`. For more info, read the [npm install docs](https://docs.npmjs.com/getting-started/installing-node). +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 modules +### Install Primer CSS -Install the primer modules you wish to use by running the npm install command. This will install the module and all the dependencies into the `node_modules` directory. +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 --save +npm install @primer/css --save ``` ### For a Jekyll site @@ -46,19 +46,19 @@ sass: - 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 your primer code and any other custom code you write. +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-core/index.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 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`. +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-utilities/index.scss"; +@import "@primer/css/utilities/index.scss"; @import "primer-buttons/index.scss"; // Import color variables for custom code @@ -82,9 +82,9 @@ Don't forget to add the compiled CSS to the `` section of your page. ``` -## Using primer on a static site +## Using Primer CSS on a static site -You won't need to install any node modules 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/build/build.css) from the npm module and host it yourself. If that's not an option, you can include a CDN link in your html: +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 the [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 inert=true diff --git a/pages/css/index.md b/pages/css/index.md index b4ac934d75..235ba602e1 100644 --- a/pages/css/index.md +++ b/pages/css/index.md @@ -43,13 +43,13 @@ Styles can be mixed and matched to achieve many different layouts, independent o ## Systematically designed for GitHub -Primer is built upon systems that form the foundation of our styles such as spacing, typography, and color. This systematic approach helps ensure our styles are consistent and interoperable with each other. +Primer CSS is built upon systems that form the foundation of our styles such as spacing, typography, and color. This systematic approach helps ensure our styles are consistent and interoperable with each other. -## Primer packages +## Primer CSS bundles -Each component or group of styles is packaged up and distributed via npm. Primer includes 23 packages that are grouped into useful meta-packages for easy install. Each package and meta-package is independently versioned and distributed via npm, so it's easy to include all or part of Primer within your own project. +Each component or group of styles is distributed via npm as a separate CSS file, or "bundle". We also distribute "meta-packages" for core (shared) elements, product-specific (github.com) styles, and marketing. @@ -69,8 +69,8 @@ Each component or group of styles is packaged up and distributed via npm. Primer
-

Use Primer in your project

-

Pick and choose what you need. Install the entire Primer bundle or individual packages via npm.

+

Use Primer CSS in your project

+

Pick and choose what you need. Install the entire Primer CSS bundle or individual packages via npm.

Installation instructions
diff --git a/pages/css/objects/layout.md b/pages/css/objects/layout.md index c16e088b37..7c27e1b490 100644 --- a/pages/css/objects/layout.md +++ b/pages/css/objects/layout.md @@ -8,7 +8,7 @@ bundle: layout --- -Primer's layout includes basic page containers and a single-tiered, fraction-based grid system. That sounds more complicated than it really is though—it's just containers, rows, and columns. +Primer CSS's layout includes basic page containers and a single-tiered, fraction-based grid system. That sounds more complicated than it really is though—it's just containers, rows, and columns. You can find all the below styles in `_layout.scss`. diff --git a/pages/css/status-key.md b/pages/css/status-key.md index da9fad19e8..7235b39323 100644 --- a/pages/css/status-key.md +++ b/pages/css/status-key.md @@ -5,7 +5,7 @@ path: status-key import StatusLabel from '../../docs/StatusLabel' -Primer is constantly evolving and we have many styles to refactor and bring up to standard. The status of each package is shown with it's corresponding documentation so you can be confident which styles are safe to use. +Primer CSS is constantly evolving and we have many styles to refactor and bring up to standard. The status of each package is shown with it's corresponding documentation so you can be confident which styles are safe to use. | Label | Description | | :----- | :--- | diff --git a/pages/css/support/index.md b/pages/css/support/index.md index b1a93a21c7..a0695cb326 100644 --- a/pages/css/support/index.md +++ b/pages/css/support/index.md @@ -6,7 +6,7 @@ bundle: support --- -Primer is built on systems that form the foundation of our styles, and inform the way we write and organize our CSS. Building upon systems helps us make styles consistent and interoperable with each other, and assists us with visual hierarchy and vertical rhythm. +Primer CSS is built on systems that form the foundation of our styles, and inform the way we write and organize our CSS. Building upon systems helps us make styles consistent and interoperable with each other, and assists us with visual hierarchy and vertical rhythm. We use Sass variables to keep color, typography, spacing, and other foundations of our system consistent. Occasionally we use Sass mixins to apply multiple CSS properties, they are a convenient solution for frequently-used verbose patterns. @@ -16,4 +16,3 @@ We've documented variables, mixins, and the systems they are built on for the fo - [Colors](/css/support/color-system) - [Spacing](/css/support/spacing) - [Typography](/css/support/typography) - diff --git a/pages/css/tools/local-primer.md b/pages/css/tools/local-primer.md index a2ebd8c602..e495293e4f 100644 --- a/pages/css/tools/local-primer.md +++ b/pages/css/tools/local-primer.md @@ -4,7 +4,7 @@ internal: true path: tools/local-primer --- -When you are working with the `github/github` codebase, you can link Primer modules with your local development environment using the Primerize script. This will allow you to make changes to primer and see them reflected on `github.localhost` without the overhead of pulling in alpha releases of a package. +When you are working with the `github/github` codebase, you can link Primer CSS modules with your local development environment using the Primerize script. This will allow you to make changes to Primer CSS and see them reflected on `github.localhost` without the overhead of pulling in alpha releases of a package. ## Prerequisites @@ -19,7 +19,7 @@ When you are working with the `github/github` codebase, you can link Primer modu └── primer ``` -## Linking to your local primer repository +## Linking to your local Primer CSS repository In your terminal start the server with the environment variable `LOCAL_PRIMER=1`. For example. @@ -27,7 +27,7 @@ In your terminal start the server with the environment variable `LOCAL_PRIMER=1` > LOCAL_PRIMER=1 script/server ``` -When the variable is present, the script will check for linked local Primer packages. If it's not linked, then it will proceed to link the primer packages in `../primer` to your GitHub application. When the server starts with successfully linked packages, you will see a clear message. +When the variable is present, the script will check for linked local Primer CSS packages. If it's not linked, then it will proceed to link the Primer CSS packages in `../primer` to your GitHub application. When the server starts with successfully linked packages, you will see a clear message. **Example output:** diff --git a/pages/css/tools/prototyping.md b/pages/css/tools/prototyping.md index a0e9c72737..4f16a52826 100644 --- a/pages/css/tools/prototyping.md +++ b/pages/css/tools/prototyping.md @@ -7,10 +7,10 @@ You're welcome to use whatever prototyping tool suits your needs, however we've The power of prototyping in code is that you can create clickable mocks that can be shared via a URL. This can be useful for exploring designs and interactions or for user research sessions. Prototypes can be throw-away, or part of your process for building out new features since you can work with the same CSS we use in production. -## Simple HTML prototype with Primer -Copy the code below and paste it in a HTML file. The CDN link is always linked to the most up to date version of Primer and includes all of the modules in the core, product, and marketing packages. +## Simple HTML prototype with Primer CSS +Copy the code below and paste it in a HTML file. The CDN link is always linked to the most up to date version of Primer CSS and includes all of the modules in the core, product, and marketing packages. -This method requires no dev environment set up and is useful for when you want to create simple prototypes using Primer. +This method requires no dev environment set up and is useful for when you want to create simple prototypes using Primer CSS. ``` @@ -27,7 +27,7 @@ This method requires no dev environment set up and is useful for when you want t ``` ## Jekyll prototyping with GitHub CSS and JavaScript -The [Jekyll](http://jekyllrb.com) based prototyping tool pulls in all of GitHub's CSS, which includes all the Primer modules as well as custom CSS modules. It includes GitHub JavaScript and octicons too. +The [Jekyll](http://jekyllrb.com) based prototyping tool pulls in all of GitHub's CSS, which includes all the Primer CSS modules as well as custom CSS modules. It includes GitHub JavaScript and octicons too. This tool is useful for when you want to build a more complex prototype with multiple pages, interactions and flows, or need to work with GitHub CSS. You can take advantage of everything you get with [Jekyll](http://jekyllrb.com/docs/home/), such as layout templates, includes, and collections. diff --git a/pages/css/utilities/marketing-type.md b/pages/css/utilities/marketing-type.md index b98fb9b59e..d7ae7a2cd9 100644 --- a/pages/css/utilities/marketing-type.md +++ b/pages/css/utilities/marketing-type.md @@ -7,7 +7,7 @@ bundle: marketing-type --- -The typography for our marketing pages differs slightly from what is in Primer's core--it is responsive, on a slightly different scale, and headlines are in a different font (Roboto). +The typography for our marketing pages differs slightly from what is in Primer CSS's core--it is responsive, on a slightly different scale, and headlines are in a different font (Roboto). ## Heading Utilities @@ -30,7 +30,7 @@ Use `.h000-mktg` – `.h6-mktg` to change an element's font, size, and weight on ## Typographic Utilities -These utilities are meant to be used in addition to Primer's core utilities. +These utilities are meant to be used in addition to Primer CSS's core utilities. ```html title="Typographic Utilities" @@ -39,4 +39,3 @@ These utilities are meant to be used in addition to Primer's core utilities.

I'm a pullquote. Someone said these words in real life, and now they're on the internet

``` - diff --git a/src/alerts/README.md b/src/alerts/README.md index 76b497dab9..3b6c2a4797 100644 --- a/src/alerts/README.md +++ b/src/alerts/README.md @@ -1,7 +1,7 @@ # Primer Alerts > Flash messages, or alerts, inform users of successful or pending actions. Use them sparingly. Don’t show more than one at a time. -This repository is a module of the full [primer][primer] repository. +This repository is a module of the full [Primer CSS][primer] repository. ## Usage