Gatsby: [docs] restructure styling section

[robinmetral]

In the styling section of the docs, there are guides about different styling methods (CSS Modules, styled-components, etc.), followed by a general article about creating global styles.

Since creating global styles varies depending on the styling method, I suggest to split this article up into the relevant guides. For example, creating Global Styles with Emotion would go into the Emotion guide.

If you also think this makes sense, I'll submit a PR :tada:
I'll also add some missing info about creating global styles with styled-components.

[marcysutton]

Hi @robinmetral, thanks for the suggestion! I agree with you, as I did not expect docs on global styles in Emotion to be in the general article about global CSS styles. I want to check with @shannonbux, though; do you have any insight into the current structure of the CSS Styling guides? Were those created based in research, and/or can we move things around a bit?

[robinmetral]

Thanks for your message @marcysutton!

I'm not sure how the current guides were created, but I don't think it would be a problem of reorganizing them a little :slightly_smiling_face: (in fact wouldn't they be all the more useful?)

Good idea to check with @shannonbux anyway, I'll get started when the confirmation comes in :rocket:

[shannonbux]

Hi @marcysutton! The current organization, titles, and content of style
docs mostly existed before I got here, so I'm not sure how they came to be.
The main thing based on research I've done are the general top-level
categories and the basic idea that each doc should be as standalone as
possible, so should cover one workflow or task and then link to related
pages.

On Thu, Feb 21, 2019 at 2:30 AM Robin Métral [e-mail]
wrote:

Thanks for your message @marcysutton https://github.com/marcysutton!

I'm not sure how the current guides were created, but I don't think it
would be a problem of reorganizing them a little 🙂 (in fact wouldn't
they be all the more useful?)

Good idea to check with @shannonbux https://github.com/shannonbux
anyway, I'll get started when the confirmation comes in 🚀

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/gatsbyjs/gatsby/issues/11490#issuecomment-465947462,
or mute the thread
https://github.com/notifications/unsubscribe-auth/Ae9o2otID1cBFaHXz6XIvNGCqA1a82XGks5vPnVigaJpZM4ae3AR
.

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

Thanks for being a part of the Gatsby community! 💪💜

[marcysutton]

Sorry for the delay on this, I'd say go ahead with the restructuring! I look forward to seeing what you come up with.

[robinmetral]

Thanks @marcysutton, I will :slightly_smiling_face:

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

Thanks for being a part of the Gatsby community! 💪💜

[marcysutton]

Hey @robinmetral, how's it going? There've been some comments about the CSS docs needing attention, and your issue came to mind. https://github.com/gatsbyjs/gatsby/issues/5997

I'm looking at these docs in the current sprint, but I wanted to check with you to see if you're still planning on contributing! Let me know if you want to pair on anything.

[robinmetral]

Hi @marcysutton, I've been a bit busy these last few weeks, but I was planning on getting to work on this starting this coming week!

I'll open a draft PR today with some initial thoughts, and we can continue the discussion over there :slightly_smiling_face:

[DSchau]

See #11490 for context.

Initial thoughts about the current styling section:

Layout Components
CSS Modules
Typography.js
Relevant as a guide in this section? It's a typography library, not a full styling approach
Using CSS-in-JS Library Emotion
Using CSS-in-JS Library Glamor
Remove, unmaintained since 2017
Using CSS-in-JS Library Styled Components
Creating Global Styles
Move sub-section related to global styles with Emotion to Emotion guide
Component CSS
Redundant with CSS Modules?
Dead link in first paragraph
PostCSS
TailwindCSS
Guide for styling with pure CSS?
Please add any other suggestions in the comments! ⬇️

Related Issues

Relevant as a guide in this section? It's a typography library, not a full styling approach

It definitely relates to style though, so I think it's relevant. I do wonder if a better guide would be typography and then mentioning Typography.js as an option?

re: removal of glamor

Yeah, I think that makes sense. We want to keep the document, but removing it from the sidebar is definitely a good idea.

Move sub-section related to global styles with Emotion to Emotion guide

I would be in favor of this, or a simple approach is to make it the last "guide" in the document, e.g. after both CSS approaches.

redundant with CSS Modules?

Not really sure it's redundant! Could you clarify that statement?

Guide for styling with pure CSS?

Yup. This is really important--we want to ensure we continue to convey that Gatsby works with whatever technology you prefer--not just hot technologies like CSS in JS or something.

I'm sure @marcysutton has a ton of other ideas here re: improved styling and docs, as well! A great next step could be a pairing session with Marcy or someone else to clarify our thoughts here and ensure we're all on the same page?

[robinmetral]

Typography.js

Relevant as a guide in this section? It's a typography library, not a full styling approach

It definitely relates to style though, so I think it's relevant. I do wonder if a better guide would be typography and then mentioning Typography.js as an option?

That's right, but isn't typography very linked to the styling approach? i.e. if I'm using styled-components, I'll declare styling rules via the createGlobalStyle API.

Maybe a styling section in each of the guides, going over the different options (including Typography.js where relevant)?

Glamor

re: removal of glamor

Yeah, I think that makes sense. We want to keep the document, but removing it from the sidebar is definitely a good idea.

:+1:

Global styles

Move sub-section related to global styles with Emotion to Emotion guide

I would be in favor of this, or a simple approach is to make it the last "guide" in the document, e.g. after both CSS approaches.

:+1:

CSS Components

redundant with CSS Modules?

Not really sure it's redundant! Could you clarify that statement?

The Component CSS guide starts with this paragraph:

Gatsby has a wealth of options available for styling components. This example will explore one very popular and useful method: CSS Modules.

It goes on with CSS Modules examples and a section on CSS Modules and BEM.

The tutorial has a similar structure, it introduces CSS Components as:

various methods of modularizing CSS to tackle styling in a component-oriented way

It follows by introducing first CSS Modules, followed by CSS-in-JS (which are also component-scoped css, in a way).

So "component CSS", or "component-scoped CSS" (I think the second term, from the tutorial, is clearer) seems to be the umbrella term for approaches ranging from Modules to CSS-in-JS solutions, as long as the CSS is scoped at the component level.

It might be worth it to explain the difference on the Styling your Site page, going over the costs (are there any? :stuck_out_tongue: ) and benefits of component-scoped vs global styling approaches.

Pure CSS

Guide for styling with pure CSS?

Yup. This is really important--we want to ensure we continue to convey that Gatsby works with whatever technology you prefer--not just hot technologies like CSS in JS or something.

:+1:

---

I'm sure @marcysutton has a ton of other ideas here re: improved styling and docs, as well! A great next step could be a pairing session with Marcy or someone else to clarify our thoughts here and ensure we're all on the same page?

I definitely agree on the pairing session, as this issue is already starting to get a bit hairy. There's only so far we can go in a thread :slightly_smiling_face:

Let me know how you'd like to proceed with this @marcysutton @DSchau

[marcysutton]

Hi @robinmetral, do you have time next week to pair? You can book time on my Calendly, I'm in Pacific time.

[robinmetral]

Sounds great @marcysutton

[marcysutton]

Great meeting today, thanks @robinmetral! Here are some notes I took on the call:

• The "Styling Your Site" landing page could use a little more orientation, while keeping it concise to act as a table of contents...particularly useful on mobile.
• It would be great to add a "Modern CSS Styling techniques" page to describe what you can do without tools or plugins (e.g. grid & flexbox), sort-of an introduction to actually styling in Gatsby (rather than installing tools).
• Create CSS-in-JS landing page to describe its purpose and available options, putting Emotion/Glamor/Styled Components pages into an accordion sub-section.
• Consider moving "Creating Global Styles" up in the page order, and/or distributing the content to specific sections (such as CSS-in-JS)
• Title updates may be a simpler option than regrouping: such as "Transform and extend CSS with PostCSS"
• Make new Frameworks & Libraries section to talk about design systems and group TailwindCSS under it? Any other frameworks we should mention, like Bootstrap?

These suggestions are free to take on (or not). The main goals would be to keep the CSS docs task-based and don't assume people know what tools are for based on their names (the "Don't Make Me Think...or click on stuff to find out" mantra).

If you have any questions or need help filling out content let us know and we can help! Thanks again for working on this, it's a huge help.

[marcysutton]

Hey @robinmetral, I DM'd you on Discord last week and didn't hear back. So I'll post here:

I wanted to check in and see how the CSS reorder in the Gatsby docs is going. I think that stuff would be really great to have in before I go speak at An Event Apart on May 6th. Let me know how your schedule is looking and I can either start a branch to collaborate with you or hold my horses! Thanks again for your offer to work on the CSS section, I think it will help ease the transition for some folks. :smiley:

[robinmetral]

Hey @marcysutton! Sorry I've been quiet (and away from Discord).

I finally got started on the issue this weekend :tada: I can submit a PR by wednesday night if that's okay for you, and we can collaborate from there on :slightly_smiling_face:

How does this sound?

[marcysutton]

That sounds fantastic! Keep me posted!

[robinmetral]

@marcysutton I'd like to group the styling approaches into categories. I've thought of a few possible solutions:

Solution A:

1. CSS in .css files (traditional CSS, CSS Modules)
2. CSS in .js files (inline styles, CSS-in-JS)

Solution B:

1. Cascading CSS (tranditonal CSS with or without preprocessors)
2. Locally-scoped CSS (CSS Modules, CSS-in-JS)

Solution C: (inspired by https://alligator.io/react/react-css/)

1. Global CSS Files (traditional CSS with or without preprocessor)
2. Modular Stylesheets (CSS Modules)
3. Stylized Components (CSS-in-JS)

What do you think would make more sense to someone getting started with styling a Gatsby site? Personally I like C. I'll start with it for the PR, let me know what you think!

[robinmetral]

@marcysutton PR submitted at #13766 :tada:

I'd love it reviewed if you have the chance, the structure of course but also the language (my English isn't native) :slightly_smiling_face: