Skip to content

Commit

Permalink
Docs updates (primer#1895)
Browse files Browse the repository at this point in the history
* Remove "Atom packages"

* Remove Docset

* Remove "Local development"

* Remove "Table object"

* Move Grid to utilities

* Remove "Objects"

* Rename nav (marketing)

* Move marketing styles to their own section

* Discourage floats

* Update padding description
  • Loading branch information
simurai authored Jan 24, 2022
1 parent 55bd498 commit d6160ea
Show file tree
Hide file tree
Showing 24 changed files with 79 additions and 321 deletions.
2 changes: 1 addition & 1 deletion docs/content/components/box.md
Original file line number Diff line number Diff line change
Expand Up @@ -554,7 +554,7 @@ You can put forms in boxes. Often form submission buttons are aligned to the bot
</div>
```

When a box is all by itself centered on a page you can use [column widths](/objects/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/utilities/typography) instead of the built in box title styles.
When a box is all by itself centered on a page you can use [column widths](/utilities/grid) to control the width of the box. If needed, break the mold a little and use [typography utilities](/utilities/typography) instead of the built in box title styles.

```html live
<div class="Box Box--spacious col-6 mx-auto text-center">
Expand Down
2 changes: 1 addition & 1 deletion docs/content/components/navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ Use `.UnderlineNav--full` in combination with container styles and `.UnderlineNa

## Side Nav

The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../objects/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content.
The Side Nav is a vertical list of navigational links, typically used on the left side of a page. For maximum flexibility, **Side Nav elements have no default width or positioning**. We suggest using [column grid](../utilities/grid) classes or an inline `width` style for sizing, and [flexbox utilities](../utilities/flexbox) for positioning alongside content.

- You can use a **border** if the parent element doesn't have it already.
- Add `aria-current="page"` to show a link as selected. Selected button elements in tab-like UIs should instead have `aria-selected="true"`.
Expand Down
13 changes: 6 additions & 7 deletions docs/content/getting-started/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,26 +9,25 @@ While this contributing guide is for GitHub employees, all contributions from th

### Components

[Components](/components) are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities and layout objects.
[Components](/components) are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities.

Decisions to add new components are made on a case-by-case basis, with help from the GitHub Design Systems team. Some questions that we use to guide these decisions include:

- How often is this pattern used across the site?
- Could these styles be achieved with existing components, objects, and utilities?
- If your design is difficult to compose with current styles, does this highlight problems with existing components (such as overly-specific components, or missing objects and utilities)?
- Could these styles be achieved with existing components and utilities?
- If your design is difficult to compose with current styles, does this highlight problems with existing components (such as overly-specific components, or missing utilities)?
- Is this a totally new pattern or should it be an extension of an existing component?
- How is this pattern being implemented currently - have you identified problems with it’s current implementation that can be improved with adding a new pattern?
- Is the desire for this new pattern a side-effect of lacking documentation or misunderstanding of use with current styles?
- Are there special factors that need to be considered as to why the this pattern needs it’s own styles? Such legal issues, usability issues, or branding and trademarks?
- Is this something that would be better handled by other front-end code rather than CSS?
- Every new addition of CSS means we ask our users to download a larger CSS file, and we increase the maintenance work of our CSS framework. Does the convenience of adding these new styles outweigh those costs?

### Objects and utilities
### Utilities

Many of the same questions can be applied to objects and utilities, however the purpose of these styles is different:
Many of the same questions can be applied to utilities, however the purpose of these styles is different:

- [Objects](/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](/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:
[Utilities](/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).
Expand Down
4 changes: 1 addition & 3 deletions docs/content/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ import {HeroLayout} from '@primer/gatsby-theme-doctocat'
import {Grid, Box, Heading, Text, ButtonOutline, BorderBox} from '@primer/components'
import {Link} from 'gatsby'
import utilitiesImage from '../src/utilities-image.svg'
import objectsImage from '../src/objects-image.svg'
import componentsImage from '../src/components-image.svg'
import typographyImage from '../src/typography-image.png'
import colorImage from '../src/color-image.svg'
Expand All @@ -22,14 +21,13 @@ Our goal is to create a system that enables us to build consistent user experien

Styles can be mixed and matched to achieve many different layouts, independent of their location. These styles fall into three categories:

<Grid gridTemplateColumns={['1fr', '1fr', 'repeat(3, 1fr)']} gridGap={5} my={5}>
<Grid gridTemplateColumns={['1fr', '1fr', 'repeat(2, 1fr)']} gridGap={5} my={5}>
{[
{
name: 'Utilities',
description: 'Single purpose, immutable styles, that do one thing well.',
image: utilitiesImage
},
{name: 'Objects', description: 'Scaffolding for common page and content layouts.', image: objectsImage},
{name: 'Components', description: 'Abstracted patterns for frequently used visual styles.', image: componentsImage}
].map(({name, description, image}) => (
<Box>
Expand Down
6 changes: 6 additions & 0 deletions docs/content/marketing/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
title: Marketing
path: marketing/index
---

The marketing components and utilities are meant for marketing pages. Note that on github.com they are not available for product pages.
6 changes: 0 additions & 6 deletions docs/content/objects/index.md

This file was deleted.

27 changes: 0 additions & 27 deletions docs/content/objects/table-object.md

This file was deleted.

25 changes: 4 additions & 21 deletions docs/content/principles/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.




## Styleguide driven design and development
Expand All @@ -14,7 +14,7 @@ Every time new CSS is added it increases our CSS bloat, CSS maintenance, and can

_If new styles are needed:_
* Use global variables where appropriate, such as spacing, typography, and color variables.
* Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, objects, and utilities as listed below.
* Write styles in a way that can be folded back into the global style guide should it become a common pattern, i.e. following our principles for naming conventions, components, and utilities as listed below.


## Obvious and transparent
Expand Down Expand Up @@ -74,26 +74,9 @@ Components make it easier to mark up a set of elements that are commonly grouped
.flash-error {...}
```

## Objects

Objects help us with common layout patterns but aren't concerned with thematic styles. Examples include the table object, the grid, and the media object. Objects essentially provide some scaffolding for layouts and should be able to be used with other objects, components, and utilities.

Example:

```html
<div class="TableObject">
<div class="TableObject-item TableObject-item--primary">
<input class="input-block" type="text" placeholder="Long flexible input form">
</div>
<div class="TableObject-item">
<button class="btn ml-3" type="button">Button</button>
</div>
</div>
```

## BEM-style naming and structure

Components and objects should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`.
Components should follow the [Block Element Modifier](http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/) (BEM) model in terms of structure. We've chosen to use a modified form of BEM syntax using [uppercase](https://en.wikipedia.org/wiki/Uppercase) for the block name, hyphens and lowercase for elements, and double-hyphens and lowercase for modifiers. When a block class requires two words use [Pascal case](https://en.wikipedia.org/wiki/PascalCase), for example `ProgressBar`. When an element or modifier class requires two words use [camel case](https://en.wikipedia.org/wiki/camelCase), for example `[Component]-closeButton` or `[Component]--extraLarge`.

* **Block**: A block includes all of the base styles you want shared across every variation of a component. Minimal thematic styling should be applied to blocks, particularly when variations of a component include visual variations. Apply additional styles with modifers rather than overriding base styles.
* **Element**: An element is part of a component. Elements should work together with other elements and can have modifiers. Element styles should not override block styles - this often results in applying more styles directly to elements rather than having styles flow down from the parent level.
Expand All @@ -116,7 +99,7 @@ Components and objects should follow the [Block Element Modifier](http://csswiza
```
## Property order
For base styles, components, and objects, follow the following property order.
For base styles and components follow the following property order.
```scss
.element {
Expand Down
2 changes: 1 addition & 1 deletion docs/content/support/breakpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ We use abbreviations for each breakpoint to keep the class names concise. This a
| Large | lg | `1012px` |
| Extra-large | xl | `1280px` |

Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/objects/grid#responsive-grids) system, and many more.
Responsive styles are available for [margin](/utilities/margin#responsive-margins), [padding](/utilities/padding#responsive-padding), [layout](/utilities/layout), [flexbox](/utilities/flexbox#responsive-flex-utilities), the [grid](/utilities/grid#responsive-grids) system, and many more.

## Breakpoint and up... 🛫

Expand Down
52 changes: 0 additions & 52 deletions docs/content/tools/atom-packages.md

This file was deleted.

18 changes: 0 additions & 18 deletions docs/content/tools/docset.md

This file was deleted.

8 changes: 1 addition & 7 deletions docs/content/tools/linting.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,7 @@ While linters shouldn't be disabled without consideration, essentially they act

### Plugins

Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](http://stylelint.io/user-guide/complementary-tools/) are available to help you lint while you code..

The Design Systems team recommends using [Atom](https://atom.io/) with the [linter-stylelint](https://github.com/AtomLinter/linter-stylelint) package installed.

![image](https://cloud.githubusercontent.com/assets/54012/21456489/6a10b370-c8f6-11e6-9199-bb3709e79794.png)

We also have a [list of Atom packages](/tools/atom-packages) that we find useful for development.
Our linter runs on every commit, but finding you have a lint error after a push can be frustrating and waste time. To avoid this, a [collection of editor plugins](https://stylelint.io/user-guide/integrations/editor) are available to help you lint while you code.

## HTML

Expand Down
Loading

0 comments on commit d6160ea

Please sign in to comment.