mirror of
https://github.com/primer/css.git
synced 2025-01-06 22:36:48 +03:00
Merge branch 'master' into toasts-v2
This commit is contained in:
simurai
GitHub
commit
406469638c
2
.github/CONTRIBUTING.md
vendored
2
.github/CONTRIBUTING.md
vendored
@ -50,7 +50,7 @@ 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 CSS modules
|
||||
### Updating Primer CSS
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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",
|
||||
]
|
||||
}
|
||||
|
||||
22
CHANGELOG.md
22
CHANGELOG.md
@ -1,3 +1,25 @@
|
||||
# 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
|
||||
|
||||
21
DEVELOP.md
21
DEVELOP.md
@ -46,26 +46,8 @@ 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/css/issues/new) and tag `@shawnbot`**. :bow:
|
||||
|
||||
### The pages directory
|
||||
The [pages directory](./pages/) contains all of the files that map to URLs on the site. Because we 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.
|
||||
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).
|
||||
|
||||
|
||||
### URL tests
|
||||
@ -101,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/`.
|
||||
|
||||
@ -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
|
||||
}
|
||||
@ -2,7 +2,6 @@ import React from 'react'
|
||||
import {Link} from '@primer/components'
|
||||
import {MarkdownHeading} from '@primer/blueprints'
|
||||
import {CodeExample} from '@primer/blueprints/next-components'
|
||||
import Outline from './Outline'
|
||||
|
||||
export const H1 = props => <MarkdownHeading {...props} />
|
||||
export const H2 = props => <MarkdownHeading as="h2" {...props} />
|
||||
@ -10,28 +9,18 @@ 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,
|
||||
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,
|
||||
// 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
|
||||
|
||||
8
package-lock.json
generated
8
package-lock.json
generated
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@primer/css",
|
||||
"version": "12.4.0",
|
||||
"version": "12.4.1",
|
||||
"lockfileVersion": 1,
|
||||
"requires": true,
|
||||
"dependencies": {
|
||||
@ -1381,9 +1381,9 @@
|
||||
}
|
||||
},
|
||||
"@primer/blueprints": {
|
||||
"version": "4.0.1",
|
||||
"resolved": "https://registry.npmjs.org/@primer/blueprints/-/blueprints-4.0.1.tgz",
|
||||
"integrity": "sha512-fGhRGcKobByuuJlIviSpR4mq2KpYZ6zMJO08x0Xw+XPEd+KPKHbap8NKbcc0qlzTmWcTo1qOaqN1AGNBjr8gzg==",
|
||||
"version": "4.0.2",
|
||||
"resolved": "https://registry.npmjs.org/@primer/blueprints/-/blueprints-4.0.2.tgz",
|
||||
"integrity": "sha512-MgX/SztcMVE2ko4l092fNV0I5YXyv3QWTYjFCF5KLTxh6PgvkGFPg8FqTlKYzLf1YPbgkoEEMtl7IUvi78Q7ZQ==",
|
||||
"dev": true,
|
||||
"requires": {
|
||||
"@githubprimer/octicons-react": "^8.1.3",
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@primer/css",
|
||||
"version": "12.4.0",
|
||||
"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.",
|
||||
@ -46,7 +46,7 @@
|
||||
"@githubprimer/octicons-react": "^8.1.3",
|
||||
"@mdx-js/mdx": "^0.16.6",
|
||||
"@mdx-js/tag": "0.15.0",
|
||||
"@primer/blueprints": "4.0.1",
|
||||
"@primer/blueprints": "4.0.2",
|
||||
"@primer/components": "12.0.1",
|
||||
"@primer/next-pages": "0.0.3",
|
||||
"@storybook/addon-viewport": "5.0.11",
|
||||
|
||||
@ -7,7 +7,7 @@ import {BaseStyles, Link, Text, BorderBox, Box, Flex, theme} from '@primer/compo
|
||||
import {PackageHeader} from '../docs/components'
|
||||
import {Header, MarkdownHeading, JumpNav, SideNav} from '@primer/blueprints'
|
||||
import {NavList} from '@primer/blueprints/next-components'
|
||||
import getComponents from '../docs/markdown'
|
||||
import components from '../docs/markdown'
|
||||
import documents from '../searchIndex'
|
||||
import {config, requirePage, rootPage} from '../docs/utils'
|
||||
import {CONTENT_MAX_WIDTH} from '../docs/constants'
|
||||
@ -36,8 +36,6 @@ export default class MyApp extends App {
|
||||
const node = rootPage.first(node => node.path === pathname) || {}
|
||||
const {file, meta = {}} = node || {}
|
||||
const isIndex = file.includes('index')
|
||||
const components = getComponents(node)
|
||||
|
||||
const Hero = file ? requirePage(file).Hero : null
|
||||
|
||||
return (
|
||||
@ -101,12 +99,12 @@ export default class MyApp extends App {
|
||||
>
|
||||
<SideNav>
|
||||
<NavList currentPath={pathname} path="/css/getting-started" />
|
||||
<NavList currentPath={pathname} path="/css/tools" />
|
||||
<NavList currentPath={pathname} path="/css/principles" />
|
||||
<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>
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -9,7 +9,7 @@ bundle: navigation
|
||||
|
||||
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
|
||||
|
||||
|
||||
@ -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>
|
||||
|
||||
@ -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.
|
||||
@ -90,12 +90,11 @@ 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:
|
||||
|
||||
@ -180,83 +179,6 @@ When using code blocks for demo purposes, you can choose to render each of the b
|
||||
```
|
||||
```
|
||||
|
||||
## Primer CSS modules
|
||||
|
||||
Modules are created for all the styles we include in the Primer framework. Modules are folders with a specific structure that include CSS, a `package.json`, and other files for publishing to repositories in our GitHub Primer organization and NPM.
|
||||
|
||||
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
|
||||
|
||||
Primer CSS follows [semantic versioning](http://semver.org/) conventions. This helps others know when a change is a patch, minor, or breaking change.
|
||||
|
||||
@ -25,6 +25,19 @@ Install the Primer CSS npm package modules by running `npm install @primer/css`.
|
||||
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:
|
||||
|
||||
@ -47,30 +47,18 @@ Primer CSS is built upon systems that form the foundation of our styles such as
|
||||
|
||||
<PrimitivesOverview />
|
||||
|
||||
## Primer CSS bundles
|
||||
|
||||
Each component or group of styles is distributed via npm as a separate CSS file, or "bundle". We also distribute "meta-packages" for core (shared) elements, product-specific (github.com) styles, and marketing.
|
||||
|
||||
<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 CSS in your project</h3>
|
||||
<p class="my-3">Pick and choose what you need. Install the entire Primer CSS bundle or individual packages via npm.</p>
|
||||
<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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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 @@ 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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
|
||||
@ -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%)); }
|
||||
|
||||
@ -2,9 +2,6 @@
|
||||
// stylelint-disable primer/selector-no-utility
|
||||
// stylelint-disable block-opening-brace-space-before, comment-empty-line-before
|
||||
|
||||
/* Add a gray border on all edges */
|
||||
.border { border: $border !important; }
|
||||
|
||||
/* Add a gray border to the left and right */
|
||||
.border-x {
|
||||
border-right: $border !important;
|
||||
@ -17,11 +14,6 @@
|
||||
border-bottom: $border !important;
|
||||
}
|
||||
|
||||
/* Change the border style to dashed, in conjunction with another utility */
|
||||
.border-dashed {
|
||||
border-style: dashed !important;
|
||||
}
|
||||
|
||||
$edges: (
|
||||
top: (top-left, top-right),
|
||||
right: (top-right, bottom-right),
|
||||
@ -88,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 */
|
||||
|
||||
Loading…
Reference in New Issue
Block a user