mirror of
https://github.com/primer/css.git
synced 2025-01-06 22:36:48 +03:00
Merge branch 'master' into flex_utilities
This commit is contained in:
simurai
commit
6f1e756253
16
.github/CONTRIBUTING.md
vendored
16
.github/CONTRIBUTING.md
vendored
@ -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
|
||||
|
||||
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
|
||||
|
||||
4
.github/ISSUE_TEMPLATE/primer-bug-report.md
vendored
4
.github/ISSUE_TEMPLATE/primer-bug-report.md
vendored
@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
name: Primer feature request
|
||||
name: Primer CSS feature request
|
||||
about: Suggest an idea for this project
|
||||
|
||||
---
|
||||
|
||||
18
.github/main.workflow
vendored
18
.github/main.workflow
vendored
@ -1,11 +1,6 @@
|
||||
workflow "lint, test, deploy, publish" {
|
||||
workflow "lint, test, publish" {
|
||||
on = "push"
|
||||
resolves = [
|
||||
"lint",
|
||||
"test",
|
||||
"publish",
|
||||
"deploy",
|
||||
]
|
||||
resolves = ["lint", "test", "publish"]
|
||||
}
|
||||
|
||||
action "install" {
|
||||
@ -31,12 +26,3 @@ action "publish" {
|
||||
args = ["--", "--unsafe-perm"]
|
||||
secrets = ["GITHUB_TOKEN", "NPM_AUTH_TOKEN"]
|
||||
}
|
||||
|
||||
action "deploy" {
|
||||
needs = "install"
|
||||
uses = "primer/deploy@v3.0.0"
|
||||
secrets = [
|
||||
"GITHUB_TOKEN",
|
||||
"NOW_TOKEN",
|
||||
]
|
||||
}
|
||||
|
||||
75
CHANGELOG.md
75
CHANGELOG.md
@ -1,3 +1,78 @@
|
||||
# 12.4.1
|
||||
|
||||
### :bug: Bug fixes
|
||||
- Fix [#822](https://github.com/primer/css/issues/822) (`.border-dashed` issues) via [#824](https://github.com/primer/css/issues/824)
|
||||
|
||||
### :memo: Documentation
|
||||
- Typos fixed in [#802](https://github.com/primer/css/issues/802) (thank you, [@The-Compiler](https://github.com/The-Compiler)!)
|
||||
- Nav updates [#803](https://github.com/primer/css/issues/803)
|
||||
- Fix tables of contents [#762](https://github.com/primer/css/issues/762)
|
||||
- Add deprecation warning for `.btn-purple`, due to disappear in 13.0.0 via [#736](https://github.com/primer/css/issues/736)
|
||||
- Lots more documentation updates in [#814](https://github.com/primer/css/issues/814)
|
||||
|
||||
### :house: Internal
|
||||
- Decommission `primer/deploy` [#809](https://github.com/primer/css/issues/809)
|
||||
|
||||
### Committers
|
||||
- [@emplums](https://github.com/emplums)
|
||||
- [@shawnbot](https://github.com/shawnbot)
|
||||
- [@simurai](https://github.com/simurai)
|
||||
- [@The-Compiler](https://github.com/The-Compiler)
|
||||
|
||||
|
||||
# 12.4.0
|
||||
|
||||
### :rocket: Enhancement
|
||||
- More responsive border utilities [#775](https://github.com/primer/css/pull/775)
|
||||
- Add `overflow: visible` utilities [#798](https://github.com/primer/css/pull/798)
|
||||
- Add `yellow` color utilities that will replace `pending` [#737](https://github.com/primer/css/pull/737)
|
||||
|
||||
### :bug: Bug Fix
|
||||
- Fix Ruby Sass compiler warnings by quoting keys in `$hue-maps` declaration [#794](https://github.com/primer/css/pull/794)
|
||||
|
||||
### :house: Internal
|
||||
- Remove `test-all-modules` scripts and old monorepo test scripts [#795](https://github.com/primer/css/pull/795)
|
||||
- Resolve all but one ([#796](https://github.com/primer/css/pull/796)) vulnerability in npm dev dependencies [#797](https://github.com/primer/css/pull/797)
|
||||
|
||||
### Committers
|
||||
- [@broccolini](https://github.com/broccolini)
|
||||
- [@shawnbot](https://github.com/shawnbot)
|
||||
- [@simurai](https://github.com/simurai)
|
||||
|
||||
# 12.3.1
|
||||
|
||||
### 🐛 Bug Fix
|
||||
- Add `aria-selected="true"` support to tabbed navigation styles to play nicely with [`<tab-container>`](https://github.com/github/tab-container-element)
|
||||
|
||||
### 🏠 Internal
|
||||
- Resolve the vulnerability alert with `tar@<4.4.2` in [CVE-2018-20834](https://nvd.nist.gov/vuln/detail/CVE-2018-20834)
|
||||
|
||||
### Committers
|
||||
- [@shawnbot](https://github.com/shawnbot)
|
||||
|
||||
# 12.3.0
|
||||
|
||||
### :rocket: Enhancement
|
||||
- More color utilities! [#760](https://github.com/primer/css/pull/760) ([@shawnbot](https://github.com/shawnbot))
|
||||
- Add pink to Primer! 💖🌸💕🌷💞🎀💗🌺💝 [#776](https://github.com/primer/css/pull/776), [#778](https://github.com/primer/css/pull/778) ([@emplums](https://github.com/emplums)))
|
||||
|
||||
### :house: Internal
|
||||
- Update storybook [#777](https://github.com/primer/css/pull/777) ([@emplums](https://github.com/emplums))
|
||||
- Add bundle size report [#772](https://github.com/primer/css/pull/772) ([@shawnbot](https://github.com/shawnbot))
|
||||
|
||||
### :memo: Documentation
|
||||
- Update Primer references to Primer CSS [#771](https://github.com/primer/css/pull/771) ([@emplums](https://github.com/emplums))
|
||||
- Add Edit on GitHub links to docs [#770](https://github.com/primer/css/pull/770) ([@emplums](https://github.com/emplums))
|
||||
- Anchor Link in Docs [#768](https://github.com/primer/css/pull/768) ([@emplums](https://github.com/emplums))
|
||||
|
||||
### :house: Internal
|
||||
- Update RELEASING [#757](https://github.com/primer/css/pull/757) ([@simurai](https://github.com/simurai))
|
||||
|
||||
### Committers
|
||||
- [@emplums](https://github.com/emplums)
|
||||
- [@shawnbot](https://github.com/shawnbot)
|
||||
- [@simurai](https://github.com/simurai)
|
||||
|
||||
# 12.2.3
|
||||
|
||||
### :bug: Bug Fix
|
||||
|
||||
34
DEVELOP.md
34
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).
|
||||
|
||||
@ -46,37 +46,9 @@ Then visit http://localhost:3000/css to view the site.
|
||||
|
||||
:rotating_light: **Warning:** Next.js has a [long-running issue](https://github.com/zeit/next.js/issues/1189) with trailing slashes in URLs. Avoid visiting `http://localhost:3000/` if possible, as this may cause your development server to fail in less-than-graceful ways.
|
||||
|
||||
|
||||
### Syncing the docs
|
||||
Both before and while the Next dev server runs, all of the Markdown files within the `src/` directory are synced to Next's `pages/` directory and rewritten to include useful metadata.
|
||||
|
||||
If, for whatever reason, the dev server isn't syncing files from `src/` to `pages/`, you have two choices:
|
||||
|
||||
1. Stop the server (`ctrl-C`) and restart it (`npm start`), which will re-sync the files and clear Next's cache.
|
||||
2. Run [script/sync](./script/sync) manually:
|
||||
|
||||
```sh
|
||||
# in the docs directory
|
||||
script/sync
|
||||
```
|
||||
|
||||
**If you find yourself needing to do this often, please [file an issue](/primer/primer/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 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](./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 `<!-- %docs -->` 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:
|
||||
@ -111,7 +83,6 @@ Our [`package.json`](package.json) houses a collection of [run-scripts] that we
|
||||
* `lint` lints all of our SCSS source files.
|
||||
* `lint-js` lints the docs site and supporting scripts.
|
||||
* `now-build` and `now-start` are run on [Now] to build and start the docs site server. `now-test` runs them both in order.
|
||||
* `sync` copies Markdown docs from `src/` to `pages/css/` and preps them for inclusion in the docs site.
|
||||
* `test-urls` compares a (pre-generated) list of paths from the [Primer Style Guide](https://styleguide.github.com/primer/) to files in `pages/css`, and lets us know if we've inadvertently deleted or renamed anything.
|
||||
* `test-migrate` tests the [`primer-migrate`](MIGRATING.md#primer-migrate) command line utility.
|
||||
* `watch` runs the sync script in watch mode, copying files as they're changed from `src/` to `pages/css/`.
|
||||
@ -124,7 +95,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/
|
||||
|
||||
66
RELEASING.md
66
RELEASING.md
@ -1,18 +1,18 @@
|
||||
# Releasing a new version of Primer CSS 🎉
|
||||
|
||||
## Prepare the release (in `primer/css`)
|
||||
|
||||
## In this repo
|
||||
1. Decide which [PRs](https://github.com/primer/css/pulls) should be part of the next release and if it will be a major, minor or patch `<version>`. You may also check the [release tracking project
|
||||
](https://github.com/primer/css/projects/2#column-4482699) or ask your team members in Slack.
|
||||
|
||||
1. Check off all of the boxes in your release PR.
|
||||
1. Create a new release branch from `master` and name it `release-<version>`.
|
||||
|
||||
1. Test your changes with the latest release candidate version [in github/github](#in-github-github).
|
||||
1. Start merging existing PRs into the release branch. Note: You have to change the base branch from `master` to the `release-<version>` branch before merging.
|
||||
|
||||
1. Once the release PR is approved and you've done necessary testing, merge it. After tests run, the site will be deployed and `@primer/css` will be published with your changes.
|
||||
|
||||
1. Create a new release branch for the next release from `master` and name it `release-<version>`. Please use the following template for the PR description, linking to the relevant issues and/or pull requests for each change, and removing irrelevant headings:
|
||||
1. Create a new PR for the `release-<version>` 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
|
||||
@ -25,13 +25,13 @@
|
||||
|
||||
### :bug: Bug Fix
|
||||
- [ ] Description #
|
||||
|
||||
|
||||
### :nail_care: Polish
|
||||
- [ ] Description #
|
||||
|
||||
|
||||
### :memo: Documentation
|
||||
- [ ] Description #
|
||||
|
||||
|
||||
### :house: Internal
|
||||
- [ ] Description #
|
||||
|
||||
@ -40,21 +40,28 @@
|
||||
### Ship checklist
|
||||
|
||||
- [ ] Update `CHANGELOG.md`
|
||||
- [ ] Update the `version` field in `package.json` to match the release version
|
||||
- [ ] [Create a new release](https://github.com/primer/css/releases/new)
|
||||
- [ ] [Update github/github](https://github.com/primer/css/blob/master/RELEASING.md#in-githubgithub)
|
||||
- [ ] Create a new pull request for the next release
|
||||
- [ ] Update the `version` field in `package.json`
|
||||
- [ ] Test the release candidate version with `github/github`
|
||||
- [ ] Merge this PR and [create a new release](https://github.com/primer/css/releases/new)
|
||||
- [ ] Update `github/github`
|
||||
|
||||
For more details, see [RELEASING.md](https://github.com/primer/css/blob/master/RELEASING.md).
|
||||
|
||||
/cc @primer/ds-core
|
||||
```
|
||||
|
||||
1. Update `CHANGELOG.md`
|
||||
|
||||
1. Update the `version` field in `package.json` to match the release version. You may also run the `npm version v<version>` command.
|
||||
|
||||
1. Wait for your checks to pass, and take note of the version that [primer/publish] lists in your status checks.
|
||||
|
||||
**ProTip:** The release candidate version will always be `<version>-rc.<sha>`, where `<version>` comes from the branch name and `<sha>` is the 7-character commit SHA.
|
||||
|
||||
### In `github/github`:
|
||||
|
||||
1. Create a new branch.
|
||||
## Test the release candidate (in `github/github`):
|
||||
|
||||
1. Create a new branch in the `github/github` repo, name it `primer-<version>`.
|
||||
|
||||
1. Update the Primer CSS version to the published release candidate with:
|
||||
|
||||
@ -62,23 +69,37 @@
|
||||
bin/npm install @primer/css@<version>-rc.<sha>
|
||||
```
|
||||
|
||||
Then commit and push the changes to `package.json`, `package-lock.json`, and `vendor/npm`.
|
||||
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.
|
||||
|
||||
1. Test on review-lab.
|
||||
|
||||
1. Publish `@primer/css` to the `latest` dist-tag by merging the release branch and waiting for [primer/publish] to finish.
|
||||
|
||||
1. Install the latest published version with:
|
||||
## Publish the release (in `primer/css`)
|
||||
|
||||
1. If the release PR got approved and you've done necessary testing, merge it.
|
||||
|
||||
After tests run, the docs site will be deployed and `@primer/css` will be published with your changes to the `latest` dist-tag. You can check [npm](https://www.npmjs.com/package/@primer/css?activeTab=versions) to see if [primer/publish] has finished.
|
||||
|
||||
1. [Create a new release](https://github.com/primer/primer/releases/new) with tag `v<version>`.
|
||||
|
||||
1. Copy the changes from the [CHANGELOG] and paste them into the release notes.
|
||||
|
||||
1. Publish 🎉
|
||||
|
||||
|
||||
## Update github.com (in `github/github`):
|
||||
|
||||
1. Install the latest published version in the same `primer-<version>` branch created earlier with:
|
||||
|
||||
```
|
||||
bin/npm install @primer/css@<version>
|
||||
```
|
||||
|
||||
Then commit and push the changes to `package.json`, `package-lock.json`, and `vendor/npm`.
|
||||
Then commit and push the changes to `package.json`, `package-lock.json`, `LICENSE` and `vendor/npm`.
|
||||
|
||||
1. Fix any breaking tests.
|
||||
|
||||
@ -87,11 +108,12 @@
|
||||
|
||||
### Publish the release
|
||||
|
||||
1. [Create a new release](https://github.com/primer/primer/releases/new) with tag `v<version>`.
|
||||
1. [Create a new release](https://github.com/primer/css/releases/new) with tag `v<version>`.
|
||||
|
||||
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
|
||||
|
||||
@ -31,6 +31,7 @@ const exceptions = {
|
||||
'/packages/primer-product': removed,
|
||||
'/principles/HTML': moved('/principles/html'),
|
||||
'/principles/SCSS': moved('/principles/scss'),
|
||||
'/tools/sketch-templates': removed,
|
||||
'/whats_new': redirect('https://github.com/primer/primer/releases'),
|
||||
'/whats_new/changelog': removed,
|
||||
'/whats_new/changelog/archived_changelog': removed,
|
||||
|
||||
@ -1,30 +0,0 @@
|
||||
import React from 'react'
|
||||
import {Box} from '@primer/components'
|
||||
|
||||
export default function Outline({outline, ...rest}) {
|
||||
if (outline && outline.length) {
|
||||
return (
|
||||
<Box as="details" mb={4}>
|
||||
<summary>Table of contents</summary>
|
||||
<OutlineList items={outline} {...rest} />
|
||||
</Box>
|
||||
)
|
||||
}
|
||||
return null
|
||||
}
|
||||
|
||||
export function OutlineList({items, ...rest}) {
|
||||
if (items && items.length) {
|
||||
return (
|
||||
<ul {...rest}>
|
||||
{items.map(item => (
|
||||
<li key={item.id}>
|
||||
<a href={`#${item.id}`}>{item.title}</a>
|
||||
<OutlineList items={item.children} />
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
return null
|
||||
}
|
||||
@ -1,28 +1,26 @@
|
||||
import React from 'react'
|
||||
import {Heading, Link} from '@primer/components'
|
||||
import {CodeExample} from '@primer/blueprints'
|
||||
import Outline from './Outline'
|
||||
import {Link} from '@primer/components'
|
||||
import {MarkdownHeading} from '@primer/blueprints'
|
||||
import {CodeExample} from '@primer/blueprints/next-components'
|
||||
|
||||
export const H1 = props => <Heading fontSize={6} fontWeight="light" {...props} />
|
||||
export const H1 = props => <MarkdownHeading {...props} />
|
||||
export const H2 = props => <MarkdownHeading as="h2" {...props} />
|
||||
export const H3 = props => <MarkdownHeading as="h3" {...props} />
|
||||
export const H4 = props => <MarkdownHeading as="h4" {...props} />
|
||||
export const H5 = props => <MarkdownHeading as="h5" {...props} />
|
||||
|
||||
export default function getComponents(page = {}) {
|
||||
const {outline: getOutline = () => []} = page
|
||||
|
||||
return {
|
||||
h1: H1,
|
||||
// render links with our component
|
||||
a: Link,
|
||||
// render code blocks with our wrapper around react-live
|
||||
code: CodeExample,
|
||||
// render the outline for <p> tags with exactly the text "{:toc}"
|
||||
p: ({children, ...rest}) => {
|
||||
if (children === '{:toc}') {
|
||||
return <Outline outline={getOutline()} {...rest} />
|
||||
} else {
|
||||
return <p {...rest}>{children}</p>
|
||||
}
|
||||
},
|
||||
// "unwrap" <pre> elements around <code> blocks
|
||||
pre: props => props.children
|
||||
}
|
||||
const components = {
|
||||
h1: H1,
|
||||
h2: H2,
|
||||
h3: H3,
|
||||
h4: H4,
|
||||
h5: H5,
|
||||
// render links with our component
|
||||
a: Link,
|
||||
// render code blocks with our wrapper around react-live
|
||||
code: CodeExample,
|
||||
// "unwrap" <pre> elements around <code> blocks
|
||||
pre: props => props.children
|
||||
}
|
||||
|
||||
export default components
|
||||
|
||||
6826
package-lock.json
generated
6826
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
25
package.json
25
package.json
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@primer/css",
|
||||
"version": "12.2.3",
|
||||
"version": "12.4.1",
|
||||
"description": "Primer is the CSS framework that powers GitHub's front-end design. primer includes 23 packages that are grouped into 3 core 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.",
|
||||
"homepage": "https://primer.style/css",
|
||||
"author": "GitHub, Inc.",
|
||||
@ -39,7 +39,6 @@
|
||||
"start-storybook": "start-storybook -p 8001",
|
||||
"build-storybook": "build-storybook -o .storybuild",
|
||||
"test": "npm-run-all -s test-urls test-migrate",
|
||||
"test-all-modules": "ava --verbose tests/test-*.js",
|
||||
"test-urls": "node docs-test/urls.js",
|
||||
"test-migrate": "script/test-migrate"
|
||||
},
|
||||
@ -47,29 +46,27 @@
|
||||
"@githubprimer/octicons-react": "^8.1.3",
|
||||
"@mdx-js/mdx": "^0.16.6",
|
||||
"@mdx-js/tag": "0.15.0",
|
||||
"@primer/blueprints": "3.0.4",
|
||||
"@primer/blueprints": "4.0.2",
|
||||
"@primer/components": "12.0.1",
|
||||
"@primer/next-pages": "0.0.3",
|
||||
"@storybook/addon-viewport": "5.0.0",
|
||||
"@storybook/react": "5.0.0",
|
||||
"@storybook/addon-viewport": "5.0.11",
|
||||
"@storybook/react": "5.0.11",
|
||||
"@svgr/webpack": "2.4.1",
|
||||
"@zeit/next-css": "^1.0.1",
|
||||
"@zeit/next-css": "1.0.1",
|
||||
"@zeit/next-sass": "^1.0.1",
|
||||
"action-status": "0.1.1",
|
||||
"autoprefixer": "9.4.7",
|
||||
"ava": "^0.23.0",
|
||||
"broken-link-checker": "^0.7.8",
|
||||
"char-spinner": "^1.0.1",
|
||||
"chroma-js": "^1.4.1",
|
||||
"clipboard-copy-element": "^0.5.0",
|
||||
"code-blocks": "^1.1.0",
|
||||
"colorette": "^1.0.7",
|
||||
"css-loader": "^0.28.4",
|
||||
"css-loader": "1.0.0",
|
||||
"cssstats": "3.3.0",
|
||||
"details-dialog-element": "^1.4.0",
|
||||
"eslint": "4.19.1",
|
||||
"eslint-plugin-github": "1.0.0",
|
||||
"execa": "^0.10.0",
|
||||
"filesize": "4.1.2",
|
||||
"fs-extra": "^4.0.2",
|
||||
"fx": "11.0.1",
|
||||
"gh-pages": "^1.0.0",
|
||||
@ -82,11 +79,9 @@
|
||||
"klaw": "3.0.0",
|
||||
"loader-utils": "^1.1.0",
|
||||
"mdx-constant": "^0.1.0",
|
||||
"metalsmith": "^2.3.0",
|
||||
"metalsmith-filter": "^1.0.2",
|
||||
"metalsmith-matters": "^1.2.0",
|
||||
"metalsmith-watch": "^1.0.3",
|
||||
"minimist": "1.2.0",
|
||||
"next": "7.0.2",
|
||||
"node-fetch": "2.4.0",
|
||||
"now": "^12.1.8",
|
||||
"npm-run-all": "4.1.5",
|
||||
"postcss": "7.0.14",
|
||||
@ -116,6 +111,8 @@
|
||||
"styled-components": "4.1.2",
|
||||
"stylelint": "9.10.1",
|
||||
"stylelint-config-primer": "7.0.0",
|
||||
"table": "5.2.3",
|
||||
"tar": "4.4.8",
|
||||
"title-case": "^2.1.1",
|
||||
"tree-model": "^1.0.7",
|
||||
"typographic-base": "^1.0.4",
|
||||
|
||||
@ -2,16 +2,22 @@ import React from 'react'
|
||||
import App, {Container} from 'next/app'
|
||||
import {MDXProvider} from '@mdx-js/tag'
|
||||
import Head from 'next/head'
|
||||
import {BaseStyles, BorderBox, Box, Flex, theme} from '@primer/components'
|
||||
import Octicon, {Pencil} from '@githubprimer/octicons-react'
|
||||
import {BaseStyles, Link, Text, BorderBox, Box, Flex, theme} from '@primer/components'
|
||||
import {PackageHeader} from '../docs/components'
|
||||
import {Header, JumpNav, Section, RouteMatch, SectionLink, SideNav} from '@primer/blueprints'
|
||||
import getComponents from '../docs/markdown'
|
||||
import {Header, MarkdownHeading, JumpNav, SideNav} from '@primer/blueprints'
|
||||
import {NavList} from '@primer/blueprints/next-components'
|
||||
import components from '../docs/markdown'
|
||||
import documents from '../searchIndex'
|
||||
import {config, requirePage, rootPage} from '../docs/utils'
|
||||
import {CONTENT_MAX_WIDTH} from '../docs/constants'
|
||||
import {repository} from '../package.json'
|
||||
|
||||
import '../src/index.scss'
|
||||
|
||||
const DocLink = props => <Link nounderline {...props} />
|
||||
const editLinkBase = `${repository}/edit/master/pages`
|
||||
|
||||
export default class MyApp extends App {
|
||||
static async getInitialProps({Component, ctx}) {
|
||||
let page = {}
|
||||
@ -27,11 +33,9 @@ export default class MyApp extends App {
|
||||
// strip the trailing slash
|
||||
const pathname = this.props.router.pathname.replace(/\/$/, '')
|
||||
const {Component, page} = this.props
|
||||
|
||||
const node = rootPage.first(node => node.path === pathname) || {}
|
||||
const {file, meta = {}} = node || {}
|
||||
const components = getComponents(node)
|
||||
|
||||
const isIndex = file.includes('index')
|
||||
const Hero = file ? requirePage(file).Hero : null
|
||||
|
||||
return (
|
||||
@ -58,7 +62,7 @@ export default class MyApp extends App {
|
||||
{Hero ? <Hero /> : null}
|
||||
<Box color="gray.9" maxWidth={['auto', 'auto', 'auto', CONTENT_MAX_WIDTH]} px={6} mx="auto" my={6}>
|
||||
<div className="markdown-body">
|
||||
{!meta.hero && meta.title ? <h1>{meta.title}</h1> : null}
|
||||
{!meta.hero && meta.title ? <MarkdownHeading>{meta.title}</MarkdownHeading> : null}
|
||||
<PackageHeader {...meta} />
|
||||
<MDXProvider components={components}>
|
||||
<Component {...page} />
|
||||
@ -69,6 +73,17 @@ export default class MyApp extends App {
|
||||
<pre>{JSON.stringify(meta, null, 2)}</pre>
|
||||
</details>
|
||||
)}
|
||||
{pathname && (
|
||||
<Box color="gray.5" borderColor="gray.2" borderTop={1} my={6} pt={2}>
|
||||
<Text mr={2}>
|
||||
<Octicon icon={Pencil} />
|
||||
</Text>
|
||||
<DocLink muted href={`${editLinkBase}${pathname}${isIndex ? '/index' : ''}.md`}>
|
||||
Edit this page
|
||||
</DocLink>{' '}
|
||||
on GitHub
|
||||
</Box>
|
||||
)}
|
||||
</div>
|
||||
</Box>
|
||||
</Box>
|
||||
@ -83,19 +98,13 @@ export default class MyApp extends App {
|
||||
borderTop={[1, 1, 0, 0]}
|
||||
>
|
||||
<SideNav>
|
||||
<Section path="/css/getting-started" />
|
||||
<Section path="/css/principles" />
|
||||
<Section path="/css/tools" />
|
||||
<Section path="/css/whats-new" />
|
||||
<RouteMatch path="/css">
|
||||
<Section>
|
||||
<SectionLink color='black' href="status-key" />
|
||||
</Section>
|
||||
<Section path="support" />
|
||||
<Section path="utilities" />
|
||||
<Section path="objects" />
|
||||
<Section path="components" />
|
||||
</RouteMatch>
|
||||
<NavList currentPath={pathname} path="/css/getting-started" />
|
||||
<NavList currentPath={pathname} path="/css/support" />
|
||||
<NavList currentPath={pathname} path="/css/utilities" />
|
||||
<NavList currentPath={pathname} path="/css/objects" />
|
||||
<NavList currentPath={pathname} path="/css/components" />
|
||||
<NavList currentPath={pathname} path="/css/tools" />
|
||||
<NavList currentPath={pathname} path="/css/principles" />
|
||||
</SideNav>
|
||||
</BorderBox>
|
||||
</Flex>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
import React from 'react'
|
||||
import {Heading} from '@primer/components'
|
||||
import {redirectTrailingSlash} from '@primer/blueprints'
|
||||
import {redirectTrailingSlash} from '@primer/blueprints/next-components'
|
||||
|
||||
export default class extends React.Component {
|
||||
static getInitialProps(context) {
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: avatars
|
||||
|
||||
Avatars are images that users can set as their profile picture. On GitHub, they're always going to be rounded squares. They can be custom photos, uploaded by users, or generated as Identicons as a placeholder.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Basic example
|
||||
|
||||
@ -154,4 +154,3 @@ For specific cases where two badges or more need to be shown as related or conne
|
||||
</ul>
|
||||
</div>
|
||||
```
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@ bundle: box
|
||||
|
||||
The `.Box` component can be used for something as simple as a rounded corner box, or more complex lists and forms. It includes optional modifiers for padding density and color themes.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Box
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: buttons
|
||||
|
||||
Buttons are used for **actions**, like in forms, while textual hyperlinks are used for **destinations**, or moving from one page to another.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Default button
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ symbols: [active, anim-scale-in, btn-link, dropdown, dropdown-caret, dropdown-di
|
||||
|
||||
Dropdowns are lightweight, JavaScript-powered context menus for housing navigation and actions. They're great for instances where you don't need the full power (and code) of the select menu.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Basic examples
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: forms
|
||||
|
||||
Style individual form controls and utilize common layouts.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
Overview:
|
||||
- We reset several elements' default styles for cross browser consistency and easier manipulation later. This includes `<fieldset>`s, WebKit validation bubbles, and most textual `<input>`s.
|
||||
@ -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 `<fieldset>`s, `<div>`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 `<fieldset>`s, `<div>`s, or other elements and styles to rearrange them.
|
||||
|
||||
```html
|
||||
<form>
|
||||
@ -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 `<select>`s for all browsers to render them consistently with textual inputs.
|
||||
Primer CSS adds light `height` and `vertical-align` styles to `<select>`s for all browsers to render them consistently with textual inputs.
|
||||
|
||||
```html
|
||||
<form>
|
||||
|
||||
@ -11,7 +11,7 @@ bundle: labels
|
||||
Labels add metatdata or indicate status of items and navigational elements. Three different types of labels are available: [Labels](#default-label-styles) for adding metadata, [States](#states) for indicating status, and [Counters](#counters) for showing the count for a number of items.
|
||||
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Labels
|
||||
|
||||
|
||||
@ -7,9 +7,9 @@ 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}
|
||||
## Table of Contents
|
||||
|
||||
## Menu
|
||||
|
||||
@ -317,5 +317,3 @@ You can also use a `subnav-search-context` to display search help in a select me
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ symbols: [account-switcher, active, admin, avatar, dropdown-menu-content, experi
|
||||
|
||||
Give a page a clear, separated title and optional top nav by adding a `.pagehead`.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Basic pagehead
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: pagination
|
||||
|
||||
Use the pagination component to apply button styles to a connected set of links that go to related pages (for example, previous, next, or page numbers).
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Previous/next pagination
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: popover
|
||||
|
||||
Popovers are used to bring attention to specific user interface elements, typically to suggest an action or to guide users through a new experience.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
A popover consist of:
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ symbols: [active, close-button, css-truncate-target, description, description-in
|
||||
|
||||
The select menu provides advanced support for navigation, filtering, and more. Any popover within a select menu can make use of JavaScript-enabled live filtering, selected states, tabbed lists, and keyboard navigation with a bit of markup.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Basic example
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: tooltips
|
||||
|
||||
Add tooltips built entirely in CSS to nearly any element.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Implementation and accessibility
|
||||
|
||||
@ -81,7 +81,7 @@ Align tooltips to the left or right of an element, combined with a directional c
|
||||
<span class="tooltipped tooltipped-sw tooltipped-align-right-1 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
|
||||
.tooltipped-sw .tooltipped-align-right-1
|
||||
</span>
|
||||
<span class="tooltipped tooltipped-se tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped SW and aigned left.">
|
||||
<span class="tooltipped tooltipped-se tooltipped-align-left-1 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
|
||||
.tooltipped-se .tooltipped-align-left-1
|
||||
</span>
|
||||
</div>
|
||||
@ -89,7 +89,7 @@ Align tooltips to the left or right of an element, combined with a directional c
|
||||
<span class="tooltipped tooltipped-sw tooltipped-align-right-2 m-2 p-2 border" aria-label="Tooltipped SE and aligned right.">
|
||||
.tooltipped-sw .tooltipped-align-right-2
|
||||
</span>
|
||||
<span class="tooltipped tooltipped-se tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped SW and aigned left.">
|
||||
<span class="tooltipped tooltipped-se tooltipped-align-left-2 m-2 p-2 border" aria-label="Tooltipped SW and aligned left.">
|
||||
.tooltipped-se .tooltipped-align-left-2
|
||||
</span>
|
||||
</div>
|
||||
|
||||
@ -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
|
||||
@ -34,16 +34,16 @@ Making a decision on whether new components should be added is done on a case by
|
||||
Many of the same questions can be applied to objects and utilities, however the purpose of these styles is different:
|
||||
* [Objects](/css/objects) aren't concerned with thematic styles. They are for common display and positioning styles we find in page layouts and common content types.
|
||||
* [Utilities](/css/utilities) do one thing well and one thing only. These styles are immutable and therefore often use the `!important` tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions:
|
||||
- how does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention.
|
||||
- is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options.
|
||||
- if this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility).
|
||||
- does introducing this new utility cause any clashes or potential confusion with the use of existing utilities? If so, what steps can we take to avoid those issues.
|
||||
- does the utility have a connection with a set of variables? If so do the corresponding variables need to be updated?
|
||||
- How does this new utility fit within our existing set of utilities? If it is an addition to an existing set then it should follow the same naming convention.
|
||||
- Is it for a property that would likely need to be changed at different breakpoints? If so it may need responsive options.
|
||||
- If this style is part of a family of properties, do we need to consider adding the full set? Reasons for adding a full set could be that the other property values are often used, or that there would be a need to switch the property on and off (such as display or visibility).
|
||||
- Does introducing this new utility cause any clashes or potential confusion with the use of existing utilities? If so, what steps can we take to avoid those issues.
|
||||
- Does the utility have a connection with a set of variables? If so do the corresponding variables need to be updated?
|
||||
|
||||
## Step-by-step instructions for adding new styles
|
||||
|
||||
### Step 1: Open an issue
|
||||
It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's and outline of what's helpful to include in a new style issue:
|
||||
It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's an outline of what's helpful to include in a new style issue:
|
||||
|
||||
1. What the pattern is and how it's being used across the site - post screenshots and urls where possible. If you need help identifying where the pattern is being used, call that out here and cc the relevant team and/or cc `@product-design` to help.
|
||||
2. Why you think a new pattern is needed (this should answer the relevant questions above).
|
||||
@ -53,7 +53,7 @@ It's usually better to open an issue before investing time in spiking out a new
|
||||
|
||||
### Step 2: Design and build the new styles
|
||||
|
||||
* You may want to explore the visual design for a new component before spiking it out in code. If so, continue in the issue and post your design mockups. Using the [Jekyll prototyping tool](https://github.com/github/design/blob/master/docs/resources/prototyping.md#jekyll) could also be a good option, it pulls in the production CSS so you can explore options in isolation before jumping into production code.
|
||||
* You may want to explore the visual design for a new component before spiking it out in code. If so, continue in the issue and post your design mockups. Using our [CodePen template](https://codepen.io/team/GitHub/pen/xYLdZd) could also be a good option, it pulls in Primer CSS so you can explore options in isolation before jumping into production code.
|
||||
* When you're ready, spike out a branch and build out your new component, object, or utilities according to the style guide principles, ensuring you follow our naming convention for each of the styles.
|
||||
* Refactor parts of the product where you think those new styles could be used to test they work for each use case. This does not mean for every instance, but enough of the key use cases to be sure the styles are flexible enough. To avoid blowing out your initial pull request we recommend you do larger amounts of refactoring in an additional branch.
|
||||
* When you're ready for review, add the `status: review needed` and the `design-systems` labels to your pull request. Follow the [ship checklist](#ship-checklist) for additional shipping steps.
|
||||
@ -72,21 +72,29 @@ 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._
|
||||
- Our documentation site for Primer CSS is built using Next.js and deployed with Now. Our site is built from the `pages` folder and uses MDX to render markdown.
|
||||
|
||||
The style guide takes a content first approach. Everything you see on the site is built from markdown files found in this folder.
|
||||
- Documentation for Primer CSS modules should live in the corresponding `.md` file for that module in the `/pages/css` folder.
|
||||
|
||||
Currently there’s a few levels of hierarchy. The top level is `styleguide/` inside the only content rendered is the `README.md` file on the style guide homepage.
|
||||
-There are separate folders in `/pages/css` for component, object, support, and utilities docs, as well as separate folders for more general documentation such as principles and tooling.
|
||||
|
||||
The folders immediately in `styleguide/` represent top level navigation. There’s a little bit of setup needed to create a new top level navigation item.
|
||||
- Each folder corresponds to a new url such as `primer.style/css/utilities`.
|
||||
|
||||
* Create a new navigation tab in the navigation partial `github/github/app/views/navigation/_styleguide.html.erb`
|
||||
- To add new documentation, locate the appropriate folder and create a new `.md` file. Be sure to include the proper front matter (at minimum, title, path and status). For example:
|
||||
|
||||
Everything inside these top level navigation items gets built into the guide for that section. `README.md` files will be returned for sections (ie. `primer`, `js`, `ruby`, `branding`) when the user is on a section landing page ie `/primer/`.
|
||||
```
|
||||
---
|
||||
title: Alerts
|
||||
path: components/alerts
|
||||
status: Stable
|
||||
source: 'https://github.com/primer/css/tree/master/src/alerts'
|
||||
bundle: alerts
|
||||
---
|
||||
```
|
||||
|
||||
### Anatomy of a guide
|
||||
### Documentation Anatomy
|
||||
|
||||
The anatomy of a style guide markdown file pretty straight forward, but has a few optional properties for making the page render special features.
|
||||
The anatomy of a Primer CSS markdown file is pretty straight forward, but has a few optional properties for making the page render special features.
|
||||
|
||||
Typically the file will look something like this:
|
||||
|
||||
@ -108,7 +116,7 @@ Typically the file will look something like this:
|
||||
|
||||
Which consists of three parts:
|
||||
|
||||
1. **YML frontmatter** _(optional)_, similar to jekyll’s frontmatter, this is a way to pass info to the controller
|
||||
1. **YML frontmatter** _(optional)_, similar to jekyll’s frontmatter, this is used to generate the sidebar and title components.
|
||||
2. **Docs section** _(required)_, This is the section between the YML and the first `````html`
|
||||
3. **The example section** _(optional)_, This section is denoted by ````html` and will render into an example used in the page. This can contain rails helpers also eg. `<%= octicons 'fire' %>`
|
||||
|
||||
@ -159,7 +167,7 @@ The source option will let you point the document to the source file. **This is
|
||||
|
||||
#### Tables of contents
|
||||
|
||||
In the style guide you can add a `{:toc}` tag to have a table of contents automatically generated.
|
||||
In pages published on [primer.style/css](https://primer.style/css), a table of contents is automatically inserted after the first `## Table of Contents` heading (if present).
|
||||
|
||||
#### Code blocks
|
||||
|
||||
@ -171,85 +179,8 @@ When using code blocks for demo purposes, you can choose to render each of the b
|
||||
```
|
||||
```
|
||||
|
||||
## Primer 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.
|
||||
|
||||
The source of truth for our CSS will be in the github/github codebase, but we publish updates to NPM whenever styles in github/github are changed. By publishing to NPM we are able to distribute our reusable modules to other GitHub properties.
|
||||
|
||||
Modules are grouped into three packages:
|
||||
- **primer-core:** modules that are used for dotcom as well as marketing websites
|
||||
- **primer-product:** modules that are only used on dotcom
|
||||
- **primer-marketing:** modules that are only used on marketing websites and occasionally for promotional content on dotcom
|
||||
|
||||
You can add module packages by including any or all of the following imports in your bundle:
|
||||
```
|
||||
@import "primer-core/index.scss"
|
||||
@import "primer-product/index.scss"
|
||||
@import "primer-marketing/index.scss"
|
||||
```
|
||||
|
||||
### Creating a module
|
||||
|
||||
1. Create a new repository on https://github.com/primer that will be the location for your module. Only the design systems team have write access to that repository. If you don't have access, ask in #design-systems and someone will create a folder for you.
|
||||
2. Create a new folder inside one of the primer directories (core, product, or marketing), and within the appropriate styles folder (components, objects, utilities etc.). This folder cannot be inside another module with a `package.json` file.
|
||||
3. Inside the folder you'll need at least a `package.json` file. Here is an example of what you'll need in the package file. The main thing it's looking for are `name, version, and repository`. The publish script uses this to push to the distribution repository.
|
||||
|
||||
```js
|
||||
{
|
||||
"name": "module-name",
|
||||
"version": "0.1.0",
|
||||
"description": "",
|
||||
"homepage": "https://github.com/styleguide",
|
||||
"license": "MIT",
|
||||
"repository": "https://github.com/primer/primer.git",
|
||||
"main": "utilities.scss",
|
||||
"bugs": {
|
||||
"url": "https://github.com/primer/primer/issues"
|
||||
},
|
||||
"author": "GitHub, Inc.",
|
||||
"scripts": {
|
||||
"test": "echo \"Error: no test specified\" && exit 1"
|
||||
},
|
||||
"keywords": [
|
||||
"primer",
|
||||
"css",
|
||||
"github",
|
||||
"primercss"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
5. The directory layout should typically be like this:
|
||||
|
||||
```
|
||||
a-module/
|
||||
├── lib/
|
||||
│ ├── partial.scss
|
||||
│ └── partial.scss
|
||||
├── index.scss
|
||||
├── README.md
|
||||
└── package.json
|
||||
```
|
||||
|
||||
Create a stylesheet named `index.scss`. In this file include a list of relative imports for the partials required, like the example below:
|
||||
|
||||
```scss
|
||||
@import "primer-support/index.scss";
|
||||
@import "./lib/button.scss";
|
||||
@import "./lib/button-group.scss";
|
||||
```
|
||||
|
||||
Add a `README` to give some info on the module and how to install it, and a documentation section. Here's an example of the [buttons README](https://github.com/primer/primer/blob/master/README.md).
|
||||
|
||||
### Publishing changes and new modules
|
||||
|
||||
Once you have your directory setup, you will be ready to publish the module.
|
||||
|
||||
To publish, there are two requirements. First, you must be on the `master` branch. Second, all changes should be committed and synced with the remote `master`. These requirements protect us from changes being overwritten. Once you're on `master` run `script/css-modules --help` to get a list of all the available commands. This script will help with versioning and publishing.
|
||||
|
||||
#### 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.
|
||||
|
||||
@ -3,28 +3,41 @@ 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
|
||||
```
|
||||
|
||||
### 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:
|
||||
@ -46,19 +59,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 +95,9 @@ 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 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
|
||||
<link href="https://unpkg.com/primer/build/build.css" rel="stylesheet">
|
||||
|
||||
@ -43,34 +43,22 @@ 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.
|
||||
|
||||
<PrimitivesOverview />
|
||||
|
||||
## Primer packages
|
||||
|
||||
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.
|
||||
|
||||
<PrimerPackageBox meta={bundles.primer} count={Object.keys(bundles).length - 1} mb={4} />
|
||||
|
||||
<Flex justifyContent="space-around" mb={6}>
|
||||
<MetaPackageBox title="Core" meta={bundles.core} width={1/3}>
|
||||
The core bundle contains styles that are shared between GitHub product and marketing websites.
|
||||
</MetaPackageBox>
|
||||
<MetaPackageBox title="Product" meta={bundles.product} width={1/3}>
|
||||
The product bundle contains styles that are used on GitHub product websites.
|
||||
</MetaPackageBox>
|
||||
<MetaPackageBox title="Marketing" meta={bundles.marketing} width={1/3}>
|
||||
The marketing bundle contains styles that are used on GitHub marketing websites.
|
||||
</MetaPackageBox>
|
||||
</Flex>
|
||||
## Structure
|
||||
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.
|
||||
|
||||
<div class="bg-gray py-6">
|
||||
<div class="d-flex flex-wrap flex-md-nowrap px-6 gutter-lg">
|
||||
<div class="col-12 col-md-9 pr-0 pr-lg-2">
|
||||
<h3 class="f3 text-normal m-0">Use Primer in your project</h3>
|
||||
<p class="my-3">Pick and choose what you need. Install the entire Primer bundle or individual packages via npm.</p>
|
||||
<h3 class="f3 text-normal m-0">Use Primer CSS in your project</h3>
|
||||
<p class="my-3">Pick and choose what you need. Install the entire Primer CSS bundle or import individual folders.</p>
|
||||
<a href="/css/getting-started" class="btn btn-outline">Installation instructions</a>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: layout
|
||||
|
||||
The grid is 12 columns and percentage-based. The number of columns a container spans can be adjusted across breakpoints for responsive layouts. The grid system works with a variety of layout utilities to achieve different results.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Float based grid
|
||||
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ path: principles/accessibility
|
||||
|
||||
Accessibility is everyone’s responsibility, and the purpose of this document is to provide general accessibility guidelines to developers and designers.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ title: HTML
|
||||
path: principles/html
|
||||
---
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## General formatting
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ path: principles/index
|
||||
|
||||
The CSS styleguide enables us to create a consistent user experience across GitHub, manage CSS bloat, and make our CSS easier to maintain. These principles should serve as guidelines for how we write and use CSS.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
|
||||
## Styleguide driven design and development
|
||||
|
||||
@ -3,7 +3,7 @@ title: SCSS
|
||||
path: priniciples/scss
|
||||
---
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Spacing
|
||||
|
||||
|
||||
@ -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 |
|
||||
| :----- | :--- |
|
||||
|
||||
@ -6,7 +6,7 @@ source: 'https://github.com/primer/css/blob/master/src/support/variables/layout.
|
||||
bundle: support
|
||||
---
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
Our breakpoints are based on screen widths where our content starts to break. Since most of GitHub is currently a fixed-width with we use pixel widths to make it easy for us to match page widths for responsive and non-responsive pages. **Our breakpoints may change as we move more of the product into responsive layouts.**
|
||||
|
||||
|
||||
@ -13,7 +13,7 @@ package:
|
||||
import {BorderBox, Box, Flex, Heading, Text} from '@primer/components'
|
||||
import {ColorPalette, ColorVariables} from '../../../docs/color-system'
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Color palette
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ source: 'https://github.com/primer/css/blob/master/src/support/variables/layout.
|
||||
bundle: support
|
||||
---
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Spacing scale
|
||||
The spacing scale is a **base-8** scale. We chose a base-8 scale because eight is a highly composable number (it can be divided and multiplied many times and result in whole numbers), yet allows spacing dense enough for GitHub's UI. The scale's exception is that it begins at 4px to allow smaller padding and margin for denser parts of the site, from there on it steps up consistently in equal values of `8px`.
|
||||
|
||||
@ -7,7 +7,7 @@ source: 'https://github.com/primer/css/blob/master/src/support/variables/typogra
|
||||
bundle: support
|
||||
---
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Type Scale
|
||||
|
||||
|
||||
@ -11,7 +11,7 @@ We keep a list of suggested packages in our [atom-packages repository](https://g
|
||||
apm install $(curl -L https://raw.githubusercontent.com/primer/atom-packages/master/packages)
|
||||
```
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Autocomplete Primer
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ For teams working on `github/github` this configuration is all setup for you. Wh
|
||||
|
||||
For everyone else we encourage you to adopt all or some of these tools in your workflow.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## CSS
|
||||
|
||||
|
||||
@ -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:**
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
```
|
||||
<!DOCTYPE html>
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Sketch templates
|
||||
internal: true
|
||||
path: tools/sketch-templates
|
||||
---
|
||||
|
||||
We often use Sketch for mocking up designs before coding them. To make this process faster and to keep our designs consistent, we have created UI kits that contain many of our commonly used styles.
|
||||
|
||||
## Product UI Kits
|
||||
|
||||
[The Product UI Kit](https://github.com/github/design/blob/master/resources/sketch/github-ui-kit.sketch) is a collection of our core GitHub UI styles and components suitable for building mockups. It also includes a starter page template with a site and repo header.
|
||||
|
||||
Don't waste time manually updating the Octicons artboard when icons are added, removed, or changed. See the [Octicons Sketch plugin](https://github.com/github/design/tree/master/resources/sketch/octicons-plugin) directory for a way to automate those updates.
|
||||
|
||||
|
||||
|
||||
## Email templates
|
||||
|
||||
[This email templates](https://github.com/github/design/blob/master/resources/sketch/email-templates.sketch) are a collection of current GitHub email templates which serve as a reference for new email designs.
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: utilities
|
||||
|
||||
Animations are reusable animation classes that you can use to emphasize an element. All of these animations will animate if you toggle their visibility using the "Toggle" button.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Fade In
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: utilities
|
||||
|
||||
Utilities for borders, border radius, and box shadows.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Default border
|
||||
|
||||
@ -21,7 +21,7 @@ The default border utility applies a solid, 1px border, with a default gray colo
|
||||
</div>
|
||||
```
|
||||
|
||||
Borders can be applied to a specific edge or to the Y axis.
|
||||
Borders can be applied to a specific edge or to the X and Y axes individually:
|
||||
|
||||
```html
|
||||
<div class="d-flex mb-3">
|
||||
@ -38,6 +38,9 @@ Borders can be applied to a specific edge or to the Y axis.
|
||||
.border-right
|
||||
</div>
|
||||
</div>
|
||||
<div class="border-x">
|
||||
.border-x
|
||||
</div>
|
||||
<div class="border-y">
|
||||
.border-y
|
||||
</div>
|
||||
@ -198,10 +201,18 @@ You can also add rounded corners to each edge (top, right, bottom, left) with th
|
||||
|
||||
## Responsive borders
|
||||
|
||||
Top, right, bottom, and left border utilities are can be used responsively to add or remove borders to an element at different screensizes.
|
||||
You can adjust border widths on all sides or each side individually with responsive border utilities:
|
||||
|
||||
* `border-(sm|md|lg|xl)` adds borders on all sides at and above the breakpoint. The `border-(sm|md|lg|xl)` shorthand is also supported.
|
||||
* `border-(sm|md|lg|xl)-0` removes borders from all sides at and above the breakpoint.
|
||||
* `border-(sm|md|lg|xl)-(top|right|bottom|left)` adds a border on the given side at and above the breakpoint.
|
||||
* `border-(sm|md|lg|xl)-(top|right|bottom|left)-0` the border from the given side at and above the breakpoint.
|
||||
|
||||
```html
|
||||
<div class="border-top border-sm-right border-md-bottom border-lg-top-0">
|
||||
.border-top-0
|
||||
<div class="border-top border-sm-right border-md-bottom border-md-top-0">
|
||||
.border-top
|
||||
<span class="d-none d-sm-inline">.border-sm-right </span>
|
||||
<span class="d-none d-md-inline">.border-md-bottom </span>
|
||||
<span class="d-none d-lg-inline">.border-md-top-0 </span>
|
||||
</div>
|
||||
```
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: utilities
|
||||
|
||||
Box shadows are used to make content appear elevated. They are typically applied to containers of content that users need to pay attention to or content that appears on top of (overlapping) other elements on the page (like a pop-over or modal).
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Default
|
||||
|
||||
|
||||
@ -75,9 +75,16 @@ Background colors are most commonly used for filling large blocks of content or
|
||||
</div>
|
||||
<div class="col-9 float-left">
|
||||
<div class="container-lg clearfix">
|
||||
<div class="h4">.bg-yellow-light</div>
|
||||
<code>{colors.yellow[2]}, $bg-yellow-light</code>
|
||||
<Swatch className="bg-yellow-light" />
|
||||
<div class="col-6 float-left">
|
||||
<div class="h4">.bg-yellow-dark</div>
|
||||
<code>{colors.yellow[7]}, $bg-yellow-dark</code>
|
||||
<Swatch className="bg-yellow-dark border-right-0" />
|
||||
</div>
|
||||
<div class="col-6 float-left">
|
||||
<div class="h4">.bg-yellow-light</div>
|
||||
<code>{colors.yellow[2]}, $bg-yellow-light</code>
|
||||
<Swatch className="bg-yellow-light" />
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@ -173,6 +180,10 @@ You can set the color inheritance on an element by using the `text-inherit` clas
|
||||
.text-orange-light on white
|
||||
</div>
|
||||
<span class="float-left text-red tooltipped tooltipped-n" aria-label="Does not meet accessibility standards"><%= octicon("alert") %></span>
|
||||
<div class="text-yellow mb-2">
|
||||
.text-yellow on white
|
||||
</div>
|
||||
<span class="float-left text-red tooltipped tooltipped-n" aria-label="Does not meet accessibility standards"><%= octicon("alert") %></span>
|
||||
<div class="text-green mb-2 ml-4">
|
||||
.text-green on white
|
||||
</div>
|
||||
@ -199,6 +210,9 @@ You can set the color inheritance on an element by using the `text-inherit` clas
|
||||
<div class="bg-green-light mb-2">
|
||||
.text-gray-dark on .bg-green-light
|
||||
</div>
|
||||
<div class="bg-yellow-dark mb-2">
|
||||
.text-gray-dark on .bg-yellow-dark
|
||||
</div>
|
||||
<div class="bg-yellow mb-2">
|
||||
.text-gray-dark on .bg-yellow
|
||||
</div>
|
||||
|
||||
@ -8,7 +8,7 @@ bundle: utilities
|
||||
|
||||
Details classes are created to enhance the native behaviors of `<details>`.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Fullscreen click area
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: utilities
|
||||
|
||||
Flex utilities can be used to apply `flexbox` behaviors to elements by using utility classes.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Required reading
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ bundle: utilities
|
||||
|
||||
Change the document layout with display, float, alignment, and other utilities.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Display
|
||||
Adjust the display of an element with `.d-block`, `.d-none`, `.d-inline`, `.d-inline-block`, `.d-table`, `.d-table-cell` utilities.
|
||||
@ -105,16 +105,18 @@ Hide utilities are able to be applied or changed per breakpoint using the follow
|
||||
Adjust the visibility of an element with `.v-hidden` and `.v-visible`.
|
||||
|
||||
## Overflow
|
||||
Adjust element overflow with `.overflow-hidden`, `.overflow-scroll`, and `.overflow-auto`. `.overflow-hidden` can also be used to create a new [block formatting context](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Block_formatting_context) or clear floats.
|
||||
Adjust element overflow with `.overflow-hidden`, `.overflow-scroll`, and `.overflow-auto`, or use `.overflow-visible` to undo the effects of CSS with overflow issues. `.overflow-hidden` can also be used to create a new [block formatting context](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Block_formatting_context) or clear floats.
|
||||
|
||||
Overflow utilities can also target x- and y-axes independently via:
|
||||
|
||||
* `.overflow-x-auto`
|
||||
* `.overflow-x-hidden`
|
||||
* `.overflow-x-scroll`
|
||||
* `.overflow-x-visible`
|
||||
* `.overflow-y-auto`
|
||||
* `.overflow-y-hidden`
|
||||
* `.overflow-y-scroll`
|
||||
* `.overflow-y-visible`
|
||||
|
||||
## Floats
|
||||
Use `.float-left` and `.float-right` to set floats, and `.clearfix` to clear.
|
||||
|
||||
@ -8,7 +8,7 @@ bundle: utilities
|
||||
|
||||
Margin utilities are based on a global [spacing scale](/css/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that share the same properties, and allows to achieve many different page layouts using the same styles.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Naming convention
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: marketing-utilities
|
||||
|
||||
Marketing layout utilities build on top of [primer-core utilities](/css/utilities/layout#position), adding the option of responsive positioning.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Position elements with spacing utilities
|
||||
|
||||
|
||||
@ -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.
|
||||
<p class="pullquote">I'm a pullquote. Someone said these words in real life, and now they're on the internet</p>
|
||||
|
||||
```
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ bundle: utilities
|
||||
|
||||
Padding utilities are based on a global [spacing scale](/css/support/spacing) which helps keep horizontal and vertical spacing consistent. These utilities help us reduce the amount of custom CSS that could share the same properties, and allows to achieve many different page layouts using the same styles.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
## Shorthand
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ bundle: utilities
|
||||
|
||||
Type utilities are designed to work in combination with line-height utilities so as to result in more sensible numbers wherever possible. These also exist as [variables](/css/support/typography#typography-variables) that you can use in components or custom CSS.
|
||||
|
||||
{:toc}
|
||||
## Table of Contents
|
||||
|
||||
Font sizes are smaller on mobile and scale up at the `md` [breakpoint](/css/support/breakpoints) to be larger on desktop.
|
||||
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
import {redirect} from '@primer/blueprints'
|
||||
import {redirect} from '@primer/blueprints/next-components'
|
||||
export default redirect('/css')
|
||||
|
||||
162
script/bundle-size-report
Executable file
162
script/bundle-size-report
Executable file
@ -0,0 +1,162 @@
|
||||
#!/usr/bin/env node
|
||||
const fetch = require('node-fetch')
|
||||
const filesize = require('filesize')
|
||||
const minimist = require('minimist')
|
||||
const {green, gray, yellow, red} = require('colorette')
|
||||
const {table, getBorderCharacters} = require('table')
|
||||
|
||||
const options = minimist(process.argv.slice(2))
|
||||
|
||||
const DELTA = '±'
|
||||
const VERSION = options.version || 'latest'
|
||||
const QUIET = options.quiet || options.q || 0
|
||||
const SORT = options.sort || options.s || 'gzip'
|
||||
// the default is descending
|
||||
const ASCENDING = options.asc || options.a
|
||||
const ONLY_BUNDLES = options.only
|
||||
const ALL_BUNDLES = !ONLY_BUNDLES && options.all
|
||||
const META_BUNDLES = options.all || options.meta || false
|
||||
|
||||
const {name} = require('../package.json')
|
||||
const unpkgBaseURL = `https://unpkg.com/${name}@${VERSION}/`
|
||||
|
||||
// ensure that K and B values line up vertically
|
||||
const filesizeConfig = {symbols: {KB: 'K'}}
|
||||
const prettySize = bytes => filesize(bytes, filesizeConfig)
|
||||
const meta = require('../dist/meta.json')
|
||||
|
||||
let bundles = Object.values(meta.bundles)
|
||||
|
||||
// fitler out support bundles, since they don't generate CSS
|
||||
bundles = bundles.filter(bundle => !isSupportBundleName(bundle.name))
|
||||
|
||||
if (ONLY_BUNDLES) {
|
||||
const only = new Set(ONLY_BUNDLES.trim().split(/\s*,\s*/))
|
||||
bundles = bundles.filter(bundle => only.has(bundle.name))
|
||||
} else if (!ALL_BUNDLES) {
|
||||
bundles = META_BUNDLES
|
||||
? bundles.filter(isMetaBundle)
|
||||
: bundles.filter(bundle => !isMetaBundle(bundle))
|
||||
}
|
||||
|
||||
Promise.all(
|
||||
bundles.map(bundle => {
|
||||
const entry = {
|
||||
name: bundle.name,
|
||||
path: bundle.css,
|
||||
local: require(`../${bundle.stats}`)
|
||||
}
|
||||
return fetch(unpkgBaseURL + bundle.stats)
|
||||
.then(res => res.json())
|
||||
.then(stats => (entry.remote = stats))
|
||||
.then(() => entry)
|
||||
})
|
||||
).then(entries => {
|
||||
const columns = [
|
||||
{title: 'name', value: get(d => d.name), alignment: 'left'},
|
||||
|
||||
// CSS selector count
|
||||
{title: 'selectors', value: get(d => d.local.selectors.total)},
|
||||
{title: DELTA, value: delta(d => d.selectors.total), id: 'selector-delta'},
|
||||
|
||||
// gzipped size (bytes)
|
||||
{title: 'gzip size', value: get(d => d.local.gzipSize, prettySize), id: 'gzip'},
|
||||
{title: DELTA, value: delta(d => d.gzipSize, prettySize), id: 'gzip-delta'},
|
||||
|
||||
// raw size (bytes)
|
||||
{title: 'raw size', value: get(d => d.local.size, prettySize), id: 'size'},
|
||||
{title: DELTA, value: delta(d => d.size, prettySize), id: 'size-delta'},
|
||||
|
||||
// path goes last
|
||||
{title: 'path', value: get(d => d.path), alignment: 'left'}
|
||||
]
|
||||
|
||||
for (const [index, column] of Object.entries(columns)) {
|
||||
column.index = index
|
||||
}
|
||||
|
||||
const header = columns.map(c => c.title)
|
||||
let data = entries.map(entry => columns.map(c => c.value(entry)))
|
||||
|
||||
if (SORT) {
|
||||
const index = columns.findIndex(c => c.id === SORT || c.title === SORT)
|
||||
if (index > -1) {
|
||||
const compare = ASCENDING ? compareAscending : compareDescending
|
||||
data.sort((a, b) => compare(a[index].value, b[index].value))
|
||||
} else {
|
||||
console.warn(`No such sort column: "${SORT}"! Output will not be sorted.`)
|
||||
}
|
||||
}
|
||||
|
||||
if (QUIET) {
|
||||
data = data.filter(cells => {
|
||||
return cells.filter((cell, i) => columns[i].title === DELTA).every(cell => cell.value !== 0)
|
||||
})
|
||||
}
|
||||
|
||||
const rows = data.map(cells => cells.map(String))
|
||||
|
||||
console.log(
|
||||
table([header].concat(rows), {
|
||||
columns,
|
||||
columnDefault: {
|
||||
alignment: 'right'
|
||||
},
|
||||
border: getBorderCharacters('norc'),
|
||||
drawHorizontalLine(index, size) {
|
||||
return index <= 1 || index === size
|
||||
}
|
||||
})
|
||||
)
|
||||
})
|
||||
|
||||
function get(getter, format = String) {
|
||||
return entry => {
|
||||
const value = getter(entry)
|
||||
return {
|
||||
value,
|
||||
toString: () => format(value)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function delta(getter, format = String, options = {}) {
|
||||
const {moreIsGood = false, badThreshold = 1000} = options
|
||||
return entry => {
|
||||
const local = getter(entry.local)
|
||||
const remote = getter(entry.remote)
|
||||
const value = local - remote
|
||||
if (value === 0) {
|
||||
return {
|
||||
value,
|
||||
toString: () => ` ${gray(0)}`
|
||||
}
|
||||
} else {
|
||||
const sign = value > 0 ? '+' : '-'
|
||||
const num = Math.abs(value)
|
||||
const good = moreIsGood ? value > 0 : value < 0
|
||||
const color = good ? green : value >= badThreshold ? red : yellow
|
||||
return {
|
||||
value,
|
||||
toString: () => color(`${sign} ${format(num)}`)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function isMetaBundle(bundle) {
|
||||
return !bundle.imports.every(isSupportBundleName)
|
||||
}
|
||||
|
||||
function isSupportBundleName(name) {
|
||||
// "support", "marketing-support", and any future ones?
|
||||
return name.endsWith('support')
|
||||
}
|
||||
|
||||
function compareAscending(a, b) {
|
||||
return a - b
|
||||
}
|
||||
|
||||
function compareDescending(a, b) {
|
||||
return b - a
|
||||
}
|
||||
@ -1,157 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
const spinner = require('char-spinner')
|
||||
const {gray, green, yellow, red, bold} = require('colorette')
|
||||
const {SiteChecker} = require('broken-link-checker')
|
||||
|
||||
const yargs = require('yargs')
|
||||
.option('excluded-schemes', {type: String, alias: 's', default: ['dash-feed', 'mailto']})
|
||||
.option('filter-level', {type: Number, alias: 'L', default: 3})
|
||||
.option('max-sockets-per-host', {type: Number, alias: 'm', default: 1})
|
||||
.option('verbose', {type: Boolean, alias: 'v', default: false})
|
||||
|
||||
const options = yargs.argv
|
||||
|
||||
const args = options._
|
||||
const VERBOSE = options.verbose
|
||||
|
||||
const pages = []
|
||||
const seen = new Set()
|
||||
const excepted = new Map()
|
||||
|
||||
const OK = ' ✓ '
|
||||
const NOT_OK = ' ✘ '
|
||||
const TAG_LENGTH = 3
|
||||
|
||||
const URL = args[0]
|
||||
if (URL) {
|
||||
log(green('go!'), bold(URL))
|
||||
} else {
|
||||
log('err', 'you must provide a URL')
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
let page = {url: URL, links: []}
|
||||
|
||||
const exceptions = {
|
||||
'GitHub private repo': url =>
|
||||
[
|
||||
// this is a list of known GitHub private repos
|
||||
'https://github.com/github/accessibility',
|
||||
'https://github.com/github/design',
|
||||
'https://github.com/github/design-systems',
|
||||
'https://github.com/github/github',
|
||||
'https://github.com/github/sentinel'
|
||||
].some(repo => url.startsWith(repo))
|
||||
}
|
||||
|
||||
const checker = new SiteChecker(options, {
|
||||
page(error, url) {
|
||||
if (error) {
|
||||
log(red('ERR'), `${url} (${error.code})`)
|
||||
} else if (page) {
|
||||
const {url, response, links = []} = page
|
||||
const num = String(links.length).padEnd(TAG_LENGTH)
|
||||
let message = `${bold(num)}${pages.length ? ' unique' : ''} links`
|
||||
if (!VERBOSE) message = `${message} on ${yellow(url)}`
|
||||
log(OK, message)
|
||||
if (links.length) {
|
||||
pages.push(page)
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
html(tree, robots, response, url) {
|
||||
if (VERBOSE) log(yellow('get'), url)
|
||||
page = {url, links: []}
|
||||
},
|
||||
|
||||
junk(result) {
|
||||
const url = result.url.resolved || result.url.original
|
||||
if (!url || seen.has(url)) {
|
||||
return
|
||||
} else if (VERBOSE) {
|
||||
log(' '.repeat(TAG_LENGTH), gray(`skip ${shorten(url)}`))
|
||||
} else if (result.excluded && url.indexOf(URL) !== 0) {
|
||||
log(yellow('---'), gray(`excluded: ${url}`))
|
||||
}
|
||||
seen.add(url)
|
||||
},
|
||||
|
||||
link(result) {
|
||||
const url = result.url.resolved || result.url.original
|
||||
if (VERBOSE && !seen.has(url)) log(' + ', gray('link'), shorten(url))
|
||||
|
||||
for (const [reason, test] of Object.entries(exceptions)) {
|
||||
if (test(url)) {
|
||||
log(yellow('---'), gray(`skip ${url}`), yellow(reason))
|
||||
excepted.set(url, reason)
|
||||
seen.add(url)
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
if (!seen.has(url)) page.links.push(result)
|
||||
seen.add(url)
|
||||
},
|
||||
|
||||
end() {
|
||||
const allBroken = []
|
||||
for (const page of pages) {
|
||||
const broken = page.links.filter(link => link.broken)
|
||||
allBroken.push(...broken)
|
||||
|
||||
if (!broken.length && !VERBOSE) {
|
||||
continue
|
||||
} else {
|
||||
const num = broken.length ? red(` ${broken.length}`.padEnd(TAG_LENGTH)) : green(' 0').padEnd(TAG_LENGTH)
|
||||
log(bold(num), `broken links on ${bold(page.url)}`)
|
||||
}
|
||||
|
||||
for (const link of page.links) {
|
||||
if (!link.broken && !VERBOSE) continue
|
||||
const tag = link.broken ? red(NOT_OK) : green(OK)
|
||||
const reason = link.broken ? link.brokenReason.replace(/HTTP_/, '') : ''
|
||||
const url = link.url.resolved || link.url.original
|
||||
log(tag, shorten(url), yellow(reason))
|
||||
link.source = url
|
||||
link.reason = reason
|
||||
}
|
||||
log('')
|
||||
}
|
||||
|
||||
if (excepted.size) {
|
||||
log(yellow(OK), `Excepted ${excepted.size} links:`)
|
||||
const exceptedURLs = Array.from(excepted.keys()).sort()
|
||||
for (const url of exceptedURLs) {
|
||||
log(yellow(OK), `${yellow(excepted.get(url))} ${gray(url)}`)
|
||||
}
|
||||
log('')
|
||||
}
|
||||
|
||||
if (allBroken.length) {
|
||||
log(red(NOT_OK), `${red(allBroken.length)} broken links:`)
|
||||
for (const link of allBroken) {
|
||||
log(red(NOT_OK), red(link.reason), link.url.original, gray('from'), shorten(link.source))
|
||||
}
|
||||
log('')
|
||||
process.exitCode = 1
|
||||
} else {
|
||||
log(green(OK), bold('0'), 'broken links')
|
||||
}
|
||||
|
||||
log('')
|
||||
}
|
||||
})
|
||||
|
||||
spinner()
|
||||
checker.enqueue(URL)
|
||||
checker.resume()
|
||||
|
||||
function log(tag, ...args) {
|
||||
spinner.clear()
|
||||
console.log(tag ? gray(`[${tag}]`) : '', ...args)
|
||||
}
|
||||
|
||||
function shorten(url) {
|
||||
return String(url).indexOf(URL) === 0 ? gray(URL) + (url.substr(URL.length) || '/') : url
|
||||
}
|
||||
@ -13,3 +13,6 @@ if [[ "$GITHUB_REF" = "refs/heads/master" ]]; then
|
||||
echo "Whoops! Failed to publish Storybook. This is not a fatal error."
|
||||
)
|
||||
fi
|
||||
|
||||
# TODO: remove this in v13
|
||||
rm -rf build/
|
||||
|
||||
@ -2,10 +2,10 @@
|
||||
set -e
|
||||
|
||||
# generate the build directory
|
||||
npm run dist
|
||||
npm run --silent dist
|
||||
|
||||
# run the selector diff report
|
||||
script/selector-diff-report
|
||||
# run the bundle size and selector diff reports
|
||||
script/run-reports
|
||||
|
||||
# TODO: remove this in v13
|
||||
mkdir -p build
|
||||
|
||||
8
script/run-reports
Executable file
8
script/run-reports
Executable file
@ -0,0 +1,8 @@
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
echo "Reporting bundle sizes..."
|
||||
script/bundle-size-report --all
|
||||
|
||||
echo "Reporting selector diffs..."
|
||||
script/selector-diff-report
|
||||
@ -2,11 +2,11 @@
|
||||
set -e
|
||||
|
||||
function log() {
|
||||
echo "$@" 1>&2
|
||||
echo "$@" 1>&2
|
||||
}
|
||||
|
||||
function warn() {
|
||||
echo "$@" 1>&2
|
||||
echo "$@" 1>&2
|
||||
}
|
||||
|
||||
pkg="@primer/css"
|
||||
@ -15,15 +15,12 @@ warn "Pulling the old $path from unpkg.com..."
|
||||
curl -sL "https://unpkg.com/$pkg/$path" > before.json
|
||||
|
||||
warn "Building the stats locally..."
|
||||
npm run --silent dist
|
||||
cp $path after.json
|
||||
|
||||
key=".selectors.values[]"
|
||||
jq -r $key before.json > before.txt
|
||||
jq -r $key after.json > after.txt
|
||||
|
||||
warn "[selector report] diff:"
|
||||
(diff before.txt after.txt | tee selector-diff.log) || log "(no diff!)"
|
||||
warn "[selector report] end"
|
||||
diff {before,after}.txt && echo 'no diff!'
|
||||
|
||||
rm {before,after}.{json,txt}
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -60,6 +60,7 @@
|
||||
|
||||
.btn { @include btn-solid($text-gray-dark, $gray-000, darken($gray-100, 2%)); }
|
||||
.btn-primary { @include btn-solid($text-white, $green-400, $green-500); }
|
||||
@warn ".btn-purple will be removed in 13.0.0. Please don't make buttons purple.";
|
||||
.btn-purple { @include btn-solid($text-white, lighten($purple-500, 5%), darken($purple-500, 5%)); }
|
||||
.btn-blue { @include btn-solid($text-white, lighten($blue-500, 8%), darken($blue-500, 2%)); }
|
||||
.btn-danger { @include btn-inverse($red-600, $gray-000, darken($gray-100, 2%)); }
|
||||
|
||||
@ -25,6 +25,7 @@
|
||||
border: 1px solid transparent;
|
||||
border-bottom: 0;
|
||||
|
||||
&[aria-selected=true],
|
||||
&.selected {
|
||||
color: $text-gray-dark;
|
||||
background-color: $bg-white;
|
||||
|
||||
@ -84,6 +84,18 @@ $purple-700: #4c2889 !default;
|
||||
$purple-800: #3a1d6e !default;
|
||||
$purple-900: #29134e !default;
|
||||
|
||||
// -------- Pink --------
|
||||
$pink-000: #ffeef8 !default;
|
||||
$pink-100: #fedbf0 !default;
|
||||
$pink-200: #f9b3dd !default;
|
||||
$pink-300: #f692ce !default;
|
||||
$pink-400: #ec6cb9 !default;
|
||||
$pink-500: #ea4aaa !default;
|
||||
$pink-600: #d03592 !default;
|
||||
$pink-700: #b93a86 !default;
|
||||
$pink-800: #99306f !default;
|
||||
$pink-900: #6d224f !default;
|
||||
|
||||
// -------- Fades --------
|
||||
// Black based on same hue as $gray-900
|
||||
$black: #1b1f23 !default;
|
||||
@ -112,3 +124,120 @@ $orange: $orange-500 !default;
|
||||
$gray-dark: $gray-900 !default;
|
||||
$gray-light: $gray-400 !default;
|
||||
$gray: $gray-500 !default;
|
||||
|
||||
// -------- Color gradient maps --------
|
||||
|
||||
$grays: (
|
||||
0: $gray-000,
|
||||
1: $gray-100,
|
||||
2: $gray-200,
|
||||
3: $gray-300,
|
||||
4: $gray-400,
|
||||
5: $gray-500,
|
||||
6: $gray-600,
|
||||
7: $gray-700,
|
||||
8: $gray-800,
|
||||
9: $gray-900,
|
||||
) !default;
|
||||
|
||||
$blues: (
|
||||
0: $blue-000,
|
||||
1: $blue-100,
|
||||
2: $blue-200,
|
||||
3: $blue-300,
|
||||
4: $blue-400,
|
||||
5: $blue-500,
|
||||
6: $blue-600,
|
||||
7: $blue-700,
|
||||
8: $blue-800,
|
||||
9: $blue-900,
|
||||
) !default;
|
||||
|
||||
$greens: (
|
||||
0: $green-000,
|
||||
1: $green-100,
|
||||
2: $green-200,
|
||||
3: $green-300,
|
||||
4: $green-400,
|
||||
5: $green-500,
|
||||
6: $green-600,
|
||||
7: $green-700,
|
||||
8: $green-800,
|
||||
9: $green-900,
|
||||
) !default;
|
||||
|
||||
$yellows: (
|
||||
0: $yellow-000,
|
||||
1: $yellow-100,
|
||||
2: $yellow-200,
|
||||
3: $yellow-300,
|
||||
4: $yellow-400,
|
||||
5: $yellow-500,
|
||||
6: $yellow-600,
|
||||
7: $yellow-700,
|
||||
8: $yellow-800,
|
||||
9: $yellow-900,
|
||||
) !default;
|
||||
|
||||
$oranges: (
|
||||
0: $orange-000,
|
||||
1: $orange-100,
|
||||
2: $orange-200,
|
||||
3: $orange-300,
|
||||
4: $orange-400,
|
||||
5: $orange-500,
|
||||
6: $orange-600,
|
||||
7: $orange-700,
|
||||
8: $orange-800,
|
||||
9: $orange-900,
|
||||
) !default;
|
||||
|
||||
$reds: (
|
||||
0: $red-000,
|
||||
1: $red-100,
|
||||
2: $red-200,
|
||||
3: $red-300,
|
||||
4: $red-400,
|
||||
5: $red-500,
|
||||
6: $red-600,
|
||||
7: $red-700,
|
||||
8: $red-800,
|
||||
9: $red-900,
|
||||
) !default;
|
||||
|
||||
$purples: (
|
||||
0: $purple-000,
|
||||
1: $purple-100,
|
||||
2: $purple-200,
|
||||
3: $purple-300,
|
||||
4: $purple-400,
|
||||
5: $purple-500,
|
||||
6: $purple-600,
|
||||
7: $purple-700,
|
||||
8: $purple-800,
|
||||
9: $purple-900,
|
||||
) !default;
|
||||
|
||||
$pinks: (
|
||||
0: $pink-000,
|
||||
1: $pink-100,
|
||||
2: $pink-200,
|
||||
3: $pink-300,
|
||||
4: $pink-400,
|
||||
5: $pink-500,
|
||||
6: $pink-600,
|
||||
7: $pink-700,
|
||||
8: $pink-800,
|
||||
9: $pink-900,
|
||||
) !default;
|
||||
|
||||
$hue-maps: (
|
||||
"gray": $grays,
|
||||
"blue": $blues,
|
||||
"green": $greens,
|
||||
"yellow": $yellows,
|
||||
"orange": $oranges,
|
||||
"red": $reds,
|
||||
"purple": $purples,
|
||||
"pink": $pinks,
|
||||
) !default;
|
||||
|
||||
@ -29,8 +29,6 @@ $border-purple: $purple !default;
|
||||
$border-red: $red !default;
|
||||
$border-red-light: desaturate($red-300, 60%) !default;
|
||||
|
||||
$border-purple: $purple !default;
|
||||
|
||||
$border-yellow: desaturate($yellow-300, 60%) !default;
|
||||
|
||||
$border-gray-dark: $gray-300 !default;
|
||||
@ -49,11 +47,13 @@ $bg-green-light: $green-100 !default;
|
||||
$bg-orange: $orange-700 !default;
|
||||
$bg-purple: $purple-500 !default;
|
||||
$bg-purple-light: $purple-000 !default;
|
||||
$bg-pink: $pink-500 !default;
|
||||
$bg-red: $red-500 !default;
|
||||
$bg-red-light: $red-100 !default;
|
||||
$bg-white: $white !default;
|
||||
$bg-yellow: $yellow-500 !default;
|
||||
$bg-yellow-light: $yellow-200 !default;
|
||||
$bg-yellow-dark: $yellow-700 !default;
|
||||
|
||||
// Text colors
|
||||
$text-blue: $blue-500 !default;
|
||||
@ -64,5 +64,7 @@ $text-green: $green-500 !default;
|
||||
$text-orange: $orange-900 !default;
|
||||
$text-orange-light: $orange-600 !default;
|
||||
$text-purple: $purple !default;
|
||||
$text-pink: $pink-500 !default;
|
||||
$text-red: $red-600 !default;
|
||||
$text-white: $white !default;
|
||||
$text-yellow: $yellow-800 !default;
|
||||
|
||||
@ -2,20 +2,18 @@
|
||||
// stylelint-disable primer/selector-no-utility
|
||||
// stylelint-disable block-opening-brace-space-before, comment-empty-line-before
|
||||
|
||||
/* Add a gray border on all sides */
|
||||
.border { border: $border !important; }
|
||||
|
||||
/* Add a gray border to the left and right */
|
||||
.border-x {
|
||||
border-right: $border !important;
|
||||
border-left: $border !important;
|
||||
}
|
||||
|
||||
/* Add a gray border to the top and bottom */
|
||||
.border-y {
|
||||
border-top: $border !important;
|
||||
border-bottom: $border !important;
|
||||
}
|
||||
|
||||
/* Remove borders from all sides */
|
||||
.border-0 { border: 0 !important; }
|
||||
|
||||
.border-dashed { border-style: dashed !important; }
|
||||
|
||||
$edges: (
|
||||
top: (top-left, top-right),
|
||||
right: (top-right, bottom-right),
|
||||
@ -23,9 +21,14 @@ $edges: (
|
||||
left: (bottom-left, top-left)
|
||||
);
|
||||
|
||||
/* Responsive gray borders */
|
||||
@each $breakpoint, $variant in $responsive-variants {
|
||||
@include breakpoint($breakpoint) {
|
||||
/* Add a gray border */
|
||||
/* Add a gray border on all sides at/above this breakpoint */
|
||||
.border#{$variant} { border: $border !important; }
|
||||
/* Set the border width to 0 on all sides at/above this breakpoint */
|
||||
.border#{$variant}-0 { border: 0 !important; }
|
||||
|
||||
/* Add a gray border to the top */
|
||||
.border#{$variant}-top { border-top: $border !important; }
|
||||
/* Add a gray border to the right */
|
||||
@ -77,6 +80,11 @@ $edges: (
|
||||
/* Add a 50% border-radius to make something into a circle */
|
||||
.circle { border-radius: 50% !important; }
|
||||
|
||||
/* Change the border style to dashed, in conjunction with another utility */
|
||||
.border-dashed {
|
||||
border-style: dashed !important;
|
||||
}
|
||||
|
||||
/* Use with .border to turn the border blue */
|
||||
.border-blue { border-color: $border-blue !important; }
|
||||
/* Use with .border to turn the border blue-light */
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
// stylelint-disable primer/selector-no-utility
|
||||
// stylelint-disable block-opening-brace-space-before, comment-empty-line-before
|
||||
|
||||
@warn ".text-pending and .bg-pending will be deprecated in 13.0.0. Use .text-yellow and .bg-yellow-dark instead";
|
||||
|
||||
// background colors
|
||||
/* Set the background to $bg-white */
|
||||
.bg-white { background-color: $bg-white !important; }
|
||||
@ -27,11 +29,23 @@
|
||||
.bg-yellow { background-color: $bg-yellow !important; }
|
||||
/* Set the background to $bg-yellow-light */
|
||||
.bg-yellow-light { background-color: $bg-yellow-light !important; }
|
||||
/* Set the background to $bg-yellow-dark */
|
||||
.bg-yellow-dark { background-color: $bg-yellow-dark !important; }
|
||||
/* Set the background to $bg-purple */
|
||||
.bg-purple { background-color: $bg-purple !important; }
|
||||
/* Set the background to $bg-pink */
|
||||
.bg-pink { background-color: $bg-pink !important; }
|
||||
/* Set the background to $bg-purple-light */
|
||||
.bg-purple-light { background-color: $bg-purple-light !important; }
|
||||
|
||||
// Generate a foreground and background utility for every shade of every hue
|
||||
@each $hue, $shades in $hue-maps {
|
||||
@each $index, $color in $shades {
|
||||
.color-#{$hue}-#{$index} { color: $color !important; }
|
||||
.bg-#{$hue}-#{$index} { background-color: $color !important; }
|
||||
}
|
||||
}
|
||||
|
||||
.bg-shade-gradient {
|
||||
background-image: linear-gradient(180deg, rgba($black, 0.065), rgba($black, 0)) !important;
|
||||
background-repeat: no-repeat !important;
|
||||
@ -51,21 +65,25 @@
|
||||
.text-gray-dark { color: $text-gray-dark !important; }
|
||||
/* Set the text color to $text-green */
|
||||
.text-green { color: $text-green !important; }
|
||||
/* Set the text color to $text-yellow */
|
||||
.text-yellow { color: $text-yellow !important; }
|
||||
/* Set the text color to $text-orange */
|
||||
.text-orange { color: $text-orange !important; }
|
||||
/* Set the text color to $text-orange-light */
|
||||
.text-orange-light { color: $text-orange-light !important; }
|
||||
/* Set the text color to $text-purple */
|
||||
.text-purple { color: $text-purple !important; }
|
||||
/* Set the text color to $text-pink */
|
||||
.text-pink { color: $text-pink !important; }
|
||||
/* Set the text color to $text-white */
|
||||
.text-white { color: $text-white !important; }
|
||||
/* Set the text color to inherit */
|
||||
.text-inherit { color: inherit !important; }
|
||||
|
||||
// Text states
|
||||
// These can probably all be regular utilities
|
||||
// Pending states
|
||||
// This will be deprecated in the future, use .text-yellow instead
|
||||
.text-pending { color: $yellow-800 !important; }
|
||||
// Separate text and background colors in future to improve a11y
|
||||
// This will be deprecated in the future, use .bg-yellow-dark instead
|
||||
.bg-pending { color: $yellow-700 !important; }
|
||||
|
||||
// Link colors
|
||||
|
||||
@ -36,17 +36,11 @@
|
||||
.v-align-baseline { vertical-align: baseline !important; }
|
||||
|
||||
// Overflow utilities
|
||||
.overflow-hidden { overflow: hidden !important; }
|
||||
.overflow-x-hidden { overflow-x: hidden !important; }
|
||||
.overflow-y-hidden { overflow-y: hidden !important; }
|
||||
|
||||
.overflow-auto { overflow: auto !important; }
|
||||
.overflow-x-auto { overflow-x: auto !important; }
|
||||
.overflow-y-auto { overflow-y: auto !important; }
|
||||
|
||||
.overflow-scroll { overflow: scroll !important; }
|
||||
.overflow-x-scroll { overflow-x: scroll !important; }
|
||||
.overflow-y-scroll { overflow-y: scroll !important; }
|
||||
@each $overflow in (visible, hidden, auto, scroll) {
|
||||
.overflow-#{$overflow} { overflow: $overflow !important; }
|
||||
.overflow-x-#{$overflow} { overflow-x: $overflow !important; }
|
||||
.overflow-y-#{$overflow} { overflow-y: $overflow !important; }
|
||||
}
|
||||
|
||||
// Clear floats
|
||||
/* Clear floats around the element */
|
||||
|
||||
@ -1,95 +0,0 @@
|
||||
const {join} = require('path')
|
||||
const fse = require('fs-extra')
|
||||
const globby = require('globby')
|
||||
const test = require('ava')
|
||||
const minimatch = require('minimatch')
|
||||
|
||||
const cwd = process.cwd()
|
||||
const css = require(cwd)
|
||||
const pkg = require(join(cwd, 'package.json'))
|
||||
|
||||
const unique = list => Array.from(new Set(list)).sort()
|
||||
|
||||
/*
|
||||
* These are the regular expressions that match what we
|
||||
* expect to be class name instances in the docs.
|
||||
* Patterns should group the matched class name(s) such that:
|
||||
*
|
||||
* ```js
|
||||
* const [, klass, ] = pattern.exec(content)
|
||||
* ```
|
||||
*/
|
||||
const classPatterns = [
|
||||
// HTML class attributes
|
||||
/class="([^"]+)"/ig,
|
||||
/:class ?=> "([^"]+)"/g,
|
||||
/class: "([^"]+)"/g,
|
||||
// assume that ERB helpers generate an element with the same class
|
||||
/<%= (\w+)\b/g,
|
||||
]
|
||||
|
||||
const whitelistClasses = (pkg.primer ? pkg.primer.class_whitelist || [] : [])
|
||||
.concat('js*')
|
||||
|
||||
const isWhitelisted = klass => {
|
||||
return whitelistClasses.some(glob => minimatch(klass, glob))
|
||||
}
|
||||
|
||||
// Find unique selectors from the cssstats selector list
|
||||
function uniqueSelectors(selectors) {
|
||||
return unique(selectors.map(s => {
|
||||
// split multi-selectors into last class used .foo .bar .baz
|
||||
return s.split(' ').pop()
|
||||
})
|
||||
.filter(s => {
|
||||
// only match exact class selectors
|
||||
return s.match(/^\.[a-z\-_]+$/ig)
|
||||
}))
|
||||
}
|
||||
|
||||
// From the given glob sources array, read the files and return found classnames
|
||||
function getDocumentedClassnames(sources) {
|
||||
return globby(sources)
|
||||
.then(paths => {
|
||||
return Promise.all(paths.map(path => {
|
||||
return fse.readFile(path, 'utf8')
|
||||
.then(content => ({path, content}))
|
||||
}))
|
||||
})
|
||||
.then(files => {
|
||||
return files.reduce((classes, {path, content}) => {
|
||||
classPatterns.forEach(pattern => {
|
||||
let match
|
||||
while (match = pattern.exec(content)) {
|
||||
// get the matched classnames and split by whitespace into classes
|
||||
let klasses = match[1].trim().split(/\s+/)
|
||||
classes.push(...klasses)
|
||||
}
|
||||
})
|
||||
return classes
|
||||
}, [])
|
||||
})
|
||||
.then(classes => unique(classes))
|
||||
}
|
||||
|
||||
const selectors = uniqueSelectors(css.cssstats.selectors.values)
|
||||
let classnames
|
||||
test.before(t => {
|
||||
return getDocumentedClassnames([
|
||||
'docs/*.md',
|
||||
'README.md'
|
||||
])
|
||||
.then(_ => (classnames = _))
|
||||
})
|
||||
|
||||
selectors.forEach(selector => {
|
||||
const klass = selector.replace(/^\./, '')
|
||||
test(`Selector "${selector}" is documented/whitelisted`, t => {
|
||||
t.plan(1)
|
||||
if (isWhitelisted(klass)) {
|
||||
t.pass(`Selector "${selector}" is whitelisted`)
|
||||
} else {
|
||||
t.is(classnames.includes(klass), true, `Selector "${selector}" is not documented`)
|
||||
}
|
||||
})
|
||||
})
|
||||
@ -1,38 +0,0 @@
|
||||
const test = require('ava')
|
||||
const fs = require('fs-extra')
|
||||
const globby = require('globby')
|
||||
const {join} = require('path')
|
||||
|
||||
const {packages} = require('../lerna.json')
|
||||
const year = (new Date()).getFullYear()
|
||||
const yearRegex = new RegExp(`Copyright \\(c\\) ${year} GitHub Inc\\.`)
|
||||
|
||||
test(`LICENSE files have the current year ${year}`, t => {
|
||||
return getPackageGlobs('LICENSE')
|
||||
.then(paths => {
|
||||
t.plan(paths.length)
|
||||
return paths.map(path => {
|
||||
const license = fs.readFileSync(path, 'utf8')
|
||||
return t.regex(license, yearRegex, `The license "${path}" does not include the current year ${year}`)
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
test(`Source header copyrights have the current year ${year}`, t => {
|
||||
return getPackageGlobs('{*.scss,lib/**/*.scss}')
|
||||
.then(paths => {
|
||||
t.plan(paths.length)
|
||||
return paths.map(path => {
|
||||
const source = fs.readFileSync(path, 'utf8')
|
||||
if (source.match(/Copyright \(c\)/)) {
|
||||
return t.regex(source, yearRegex, `The source's header "${path}" does not include the current year ${year}`)
|
||||
} else {
|
||||
return t.true(true)
|
||||
}
|
||||
})
|
||||
})
|
||||
})
|
||||
|
||||
function getPackageGlobs(glob) {
|
||||
return globby(packages.map(pkg => join(pkg, glob)))
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user