Skip to content

Commit

Permalink
[docs] Restructure styling section (gatsbyjs#13766)
Browse files Browse the repository at this point in the history 
* Add comment to create draft PR

* Add comment to create draft PR

* Draft styling section structure

* Draft styling section intro

* Remove guide from Glamor, poin to Emotion

Keep the file to avoid any broken links, but discourage using it

* Write CSS-in-JS section intro

* Write Cascading and Scoped styles intro

* Write Frameworks and Libraries intro

* Write stubs

* Remove Component CSS page

This was essentially a duplicate of CSS Modules, with an intro to component-scoped CSS.
Keeping the page to avoid broken links, redirecting to Scoped Styles

* Structure in three sub-sections

1. Global CSS Files
2. Mudular CSS
3. Stylized Components
(4. other frameworks and libraries)

* Write Global CSS intro

* Copy content from Global Styles to Global CSS approach

* Copy content from Global Styles to Emotion guide

* Rewrite Styling section intro

* Add page at creating-global-styles to avoid broken links

* Add links in styling approaches description

* Write CSS-in-JS motivations draft

* Rewrite approaches titles

* Apply language and details suggestions from review

Co-Authored-By: robinmetral <[email protected]>

* Rename page to fit section order

CSS Frameworks and Libraries -> CSS Libraries and Frameworks

* Add note about stable classes for user stylesheets

* Add section on importing CSS files into components

* Update CSS-in-JS from suggestion

Mention there are global style sections in each CSS-in-JS guide

Co-Authored-By: Marcy Sutton <[email protected]>

* Rewrite CSS Modules page with component CSS intro

* title tweaks and content updates

* Redirect Component CSS to CSS Modules

* Apply suggestions from code review

Co-Authored-By: gillkyle <[email protected]>

* Improve links out to guides on Global Styles page

* chore: format

* fix heading levels
  • Loading branch information
@robinmetral
robinmetral authored and Marcy Sutton committed May 20, 2019
1 parent 4b45857 commit af89cf3
Show file tree
Hide file tree
Showing 13 changed files with 347 additions and 353 deletions.
48 changes: 0 additions & 48 deletions docs/docs/component-css.md
View file

This file was deleted.

168 changes: 4 additions & 164 deletions docs/docs/creating-global-styles.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,168 +2,8 @@
title: Creating global styles
---

In nearly every site, there will be some global styles, such as a reset or typography defaults. This guide will walk through how to add global styles to your site, whether you use standard `.css` files (or with preprocessors like Sass/Less) or a CSS-in-JS solution.
Creating global styles for your Gatsby site depends on your styling approach, so we've moved the instructions to the relevant guides:

## Table of Contents

- [How to add global styles in Gatsby with standard CSS files](#how-to-add-global-styles-in-gatsby-with-standard-css-files)
- [How to add global styles in Gatsby using CSS-in-JS](#how-to-add-global-styles-in-gatsby-using-css-in-js)
- [Add global styles with CSS files and no layout component](#add-global-styles-with-css-files-and-no-layout-component)

## How to add global styles in Gatsby with standard CSS files

The best way to add global styles is with a [shared layout component](/tutorial/part-three/#your-first-layout-component). This layout component is used for things that are shared throughout the site, including styles, header components, and other common items.

> **NOTE:** This pattern is implemented by default in [the default starter](https://github.com/gatsbyjs/gatsby-starter-default/blob/02324e5b04ea0a66d91c7fe7408b46d0a7eac868/src/layouts/index.js#L6).
To create a shared layout with global styles, start by creating a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world).

```shell
gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world
```

Open your new site in your code editor and create a new directory at `/src/components`. Inside, create two new files:

```diff
global-styles/
└───src/
└───components/
+ │ │─ layout.js
+ │ └─ layout.css
│
└───pages/
└─ index.js
```

Inside `src/components/layout.css`, add some global styles:

```css:title=src/components/layout.css
div {
background: red;
color: white;
}
```

In `src/components/layout.js`, include the stylesheet and export a layout component:

```jsx:title=src/components/layout.js
import React from "react"
import "./layout.css"

export default ({ children }) => <div>{children}</div>
```

Finally, update `src/pages/index.js` to use the new layout component:

```jsx:title=src/pages/index.js
import React from "react"
import Layout from "../components/layout"

export default () => <Layout>Hello world!</Layout>
```

Run `npm run develop` and you’ll see the global styles applied.

![Global styles](./images/global-styles.png)

## How to add global styles in Gatsby using CSS-in-JS

> **NOTE:** For this example, we’ll be using [Emotion](https://emotion.sh), but the implementation is similar for other CSS-in-JS solutions as well.
To start, create a new Gatsby site with the [hello world starter](https://github.com/gatsbyjs/gatsby-starter-hello-world) and install [`gatsby-plugin-emotion`](/packages/gatsby-plugin-emotion/) and its dependencies:

```shell
gatsby new global-styles https://github.com/gatsbyjs/gatsby-starter-hello-world
cd global-styles
npm install --save gatsby-plugin-emotion @emotion/core @emotion/styled
```

Create `gatsby-config.js` and add the Emotion plugin:

```js:title=gatsby-config.js
module.exports = {
plugins: [`gatsby-plugin-emotion`],
}
```

Next, add a layout component at `src/components/layout.js`:

```jsx:title=src/components/layout.js
import React from "react"
import { Global, css } from "@emotion/core"
import styled from "@emotion/styled"

const Wrapper = styled("div")`
border: 2px solid green;
padding: 10px;
`

export default ({ children }) => (
<Wrapper>
<Global
styles={css`
div {
background: red;
color: white;
}
`}
/>
{children}
</Wrapper>
)
```

Then, update `src/pages/index.js` to use the layout:

```jsx:title=src/pages/index.js
import React from "react"
import Layout from "../components/layout"

export default () => <Layout>Hello world!</Layout>
```

Run `npm run build`, and you can see in `public/index.html` that the styles have been inlined globally.

## Add global styles with CSS files and no layout component

In some cases, using a shared layout component is not desirable. In these cases, you can include a global stylesheet using `gatsby-browser.js`.

> **NOTE:** This approach does _not_ work with CSS-in-JS. Use shared components to share styles in CSS-in-JS.
First, open a new terminal window and run the following commands to create a new default Gatsby site and start the development server:

```shell
gatsby new global-style-tutorial https://github.com/gatsbyjs/gatsby-starter-default
cd global-style-tutorial
npm run develop
```

Second, create a css file and define any styles you wish. An arbitrary example:

```css:title=src/styles/global.css
html {
background-color: peachpuff;
}

a {
color: rebeccapurple;
}
```

Then, include the stylesheet in your site's `gatsby-browser.js` file.

> **NOTE:** This solution works when including css as those styles are extracted when building the JavaScript but not for css-in-js.
> Including styles in a layout component or a global-styles.js is your best bet for that.
```javascript:title=gatsby-browser.js
import "./src/styles/global.css"

// or:
// require('./src/styles/global.css')
```

> _Note: You can use Node.js require or import syntax. Additionally, the placement of the example css file in a `src/styles` folder is arbitrary._
You should see your global styles taking effect across your site:

![Global styles example site](./images/global-styles-example.png)
- [Global styles with standard CSS files](/docs/global-css/) (also applies if you're using CSS Modules for component-scoped styles)
- [Global styles with CSS-in-JS library Emotion](/docs/emotion/)
- [Global styles with CSS-in-JS library Styled-Components](/docs/styled-components/)
23 changes: 23 additions & 0 deletions docs/docs/css-in-js.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
title: Enhancing Styles with CSS-in-JS
overview: true
---

CSS-in-JS refers to an approach where styles are written in JavaScript instead of in external CSS files to easily scope styles in components, eliminate dead code, encourage faster performance and dynamic styling, and more.

CSS-in-JS bridges the gap between CSS and JavaScript:

1. **Components**: you'll style your site with components, which integrates well with React's "everything is a component" philosophy.
2. **Scoped**: this is a side effect of the first. Just like [CSS Modules](/docs/css-modules/), CSS-in-JS is scoped to components by default.
3. **Dynamic**: style your site dynamically based on component state by integrating JavaScript variables.
4. **Bonuses**: many CSS-in-JS libraries generate unique class names which can help with caching, automatic vendor prefixes, timely loading of critical CSS, and implementing many other features, depending on the library you choose.

CSS-in-JS, while not required in Gatsby, is very popular among JavaScript developers for the reasons listed above. For more context, read Max Stoiber's (creator of CSS-in-JS library [styled-components](/docs/styled-components/)) article [_Why I write CSS in JavaScript_](https://mxstbr.com/thoughts/css-in-js/). However, you should also consider whether CSS-in-JS is necessary, as not relying on it can encourage more inclusive front-end skill-sets. It is also more difficult to port styles from JSX to and from CSS.

_Note that this functionality is not a part of React or Gatsby, and requires using any of the many [third-party CSS-in-JS libraries](https://github.com/MicheleBertoli/css-in-js#css-in-js)._

> Adding a stable CSS class to your JSX markup along with your CSS-in-JS can make it easier to users to include [User Stylesheets](https://www.viget.com/articles/inline-styles-user-style-sheets-and-accessibility/) for accessibility. See [Styled Components](/docs/styled-components#enabling-user-stylesheets-with-a-stable-class-name) example.
This section contains guides for styling your site with some of the most popular CSS-in-JS libraries, including how to set up global styles using each library.

[[guidelist]]
10 changes: 10 additions & 0 deletions docs/docs/css-libraries-and-frameworks.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: CSS Libraries and Frameworks
overview: true
---

There are many other CSS libraries and frameworks that you can use in your Gatsby project.

These are not full-on approaches to styling, and generally work no matter which styling approach you've chosen for your website. They require installing third-party libraries, often with the help of Gatsby community plugins.

[[guidelist]]
71 changes: 55 additions & 16 deletions docs/docs/css-modules.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,67 @@
---
title: CSS Modules
title: Component-Scoped Styles with CSS Modules
---

## CSS modules and Gatsby
Component-scoped CSS allows you to write traditional, portable CSS with minimal side-effects: gone are the worries of selector name collisions or affecting other components' styles.

Gatsby works out of the box with CSS Modules. Here is an [example site that uses CSS modules](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-css-modules).
Gatsby works out of the box with [CSS Modules](https://github.com/css-modules/css-modules), a popular solution for writing component-scoped CSS. Here is an [example site that uses CSS Modules](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-css-modules).

## What is a CSS module?
## What is a CSS Module?

Quoting from
[the CSS Module homepage](https://github.com/css-modules/css-modules):
Quoting from [the CSS Module homepage](https://github.com/css-modules/css-modules):

> A **CSS Module** is a CSS file in which all class names and animation names
> are scoped locally by default.
> A **CSS Module** is a CSS file in which all class names and animation names are scoped locally by default.
CSS Modules are very popular as they let you write CSS like normal but with a lot
more safety. The tool automatically makes class and animation names unique so
you don't have to worry about selector name collisions.
CSS Modules let you write styles in CSS files but consume them as JavaScript objects for additional processing and safety. CSS Modules are very popular because they automatically make class and animation names unique so you don't have to worry about selector name collisions.

## When to use CSS modules
### CSS Module example

CSS Modules are highly recommended for those new to building with Gatsby (and
React in general).
The CSS in a CSS module is no different than normal CSS, but the extension of the file is different to mark that the file will be processed.

## How to build a page using CSS modules
```css:title=src/components/container.module.css
.container {
margin: 3rem auto;
max-width: 600px;
}
```

Visit the [CSS Modules section of the tutorial](/tutorial/part-two/#css-modules) to learn how to build a page using CSS modules.
```jsx:title=src/components/container.js
import React from "react"
// highlight-next-line
import containerStyles from "./container.module.css"

export default ({ children }) => (
// highlight-next-line
<section className={containerStyles.container}>{children}</section>
)
```

In this example, a CSS module is imported and declared as a JavaScript object called `containerStyles`. Then, a CSS class from that object is referenced in the JSX `className` attribute with `containerStyles.container`, which renders into HTML with dynamic CSS class names like `container-module--container--3MbgH`.

### Enabling user stylesheets with a stable class name

Adding a persistent CSS `className` to your JSX markup along with your CSS Modules code can make it easier for users to take advantage of [User Stylesheets](https://www.viget.com/articles/inline-styles-user-style-sheets-and-accessibility/) for accessibility.

Here's an example where the class name `container` is added to the DOM along with the module's dynamically-created class names:

```jsx:title=src/components/container.js
import React from "react"
import containerStyles from "./container.module.css"

export default ({ children }) => (
<section className={`container ${containerStyles.container}`}>
{children}
</section>
)
```

A site user could then write their own CSS styles matching HTML elements with a class name of `.container`, and it wouldn't be affected if the CSS module name or path changed.

## When to use CSS Modules

CSS Modules are highly recommended for those new to building with Gatsby (and React in general) as they allow you to write regular, portable CSS files while gaining
performance benefits like only bundling referenced code.

## How to build a page using CSS Modules

Visit the [CSS Modules section of the tutorial](/tutorial/part-two/#css-modules) for a guided tour of building a page with CSS Modules.
Loading

0 comments on commit af89cf3

Please sign in to comment.