Gatsby: [docs][guides] Styling Gatsby Themes

[marcysutton]

Summary

It would be helpful to create a new Reference Guide in the Gatsby Themes docs that outlines options for styling themes, including regular CSS files/imports as well as Theme UI. It could link to the various Styling Your Site docs including the Theme UI docs page under CSS Libraries & Frameworks, as well.

Motivation

Through feedback, users have said they would like additional docs on how to use Gatsby Themes. Styling is a huge part of this, and it would be helpful to outline multiple approaches to help users learn how to use Themes.

Note: while Theme UI is a big part this and its power and advantages should be illustrated, this guide should also support users who are less interested in CSS-in-JS by including CSS approaches that don't rely as heavily on JavaScript syntax.

Resources

Please refer to the Gatsby contributing docs to ensure your PR is accepted:

• Gatsby Style Guide
• Reference Guide template
• How to open a PR, including local docs site setup info

[makeupsomething]

If it is available I'd love to have a go at this!

[thomaswang]

@makeupsomething awesome, I think this one will be super impactful!

Something to add – I think Themes for a designer or non-developer typically means styling and templating of a website. I think this PR could incorporate a doc that explains how to use Themes in this way, perhaps a new name or subset of the broader Themes category?

For this issue and PR, please reference #18242 because I'd like to make sure it fits nicely with the overall Themes workflow ☺️

[makeupsomething]

@thomaswangio Thanks! I've had a look at #18242 and can definitely see what you are going for. This is the way I have always thought about Gatsby themes but as you say this is not that clear in the current documentation.

perhaps a new name or subset of the broader Themes category

I was thinking about a new name or possible subsection called "Templates" but I am not sure if that is a completely accurate description.

[thomaswang]

possible subsection called "Templates"

I like this! Should ask @marcysutton what the best way is to create this subsection?

[marcysutton]

Great question (and thanks for your patience)! I agree, this is very related to the Themes Workflow and it provides an opportunity to clarify what Gatsby themes are and how styling fits into them. I do think we need to be careful about introducing new terminology or definitions, especially since Gatsby "themes" already provide a bit of a learning curve.

Themes are a type of plugin with a gatsby-config.js file which can include functionality (like source queries and configurations) as well as UI component code. There are already templates in the context of programmatically-created posts and pages, so I could see the name 'Templates' being confusing in the context of Themes (which may or may not refer to the same thing).

What do you envision going into such a subsection for styling with themes? Some types of information I envision for this are how to use different types of CSS with a theme: global and component CSS files, using the Sass plugin (where would you install it?), and how Theme UI fits into the picture. Something like "Organizing Layouts and Components in Themes" could potentially be more clear: what do you think?

Somewhat related: I got a question just the other day on Twitter about what layout components are, so I'm sure it would help to address this in the docs every chance we get. (I'd call a layout component a type of component for composing reusable markup and styles into something you can import into your pages, posts, and potentially other components.) Curious to hear your thoughts!

[makeupsomething]

Sorry for the delay getting back to this!

I agree using the work "Templates" would be confusing in this context.

What do you envision going into such a subsection for styling with themes?
I think it should include pretty much what you have described here.
Styling themes wth different types of CSS, or using Theme UI. Maybe as an example I would take a theme and apply the same styles to it using these different techniques.

About layout components. I think we could definitely address that in this section too. Talking about the difference between a layout component and a theme could be a helpful starting point for a lot of users.

[marcysutton]

That sounds great, @makeupsomething! Do you have the information you need to move forward?

[makeupsomething]

Sure! I'l be able to move forward with it this weekend! Too late for hacktoberfest but thats not my main motivation. Thank you for the help and advice on this so far!

[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!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

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

[marcysutton]

Hi @makeupsomething, I wanted to check up on this issue. Are you still interested in contributing a doc on Styling Gatsby Themes?

[marcysutton]

I'm opening this one back up to the community by removing an assignment, if anyone is interested in working on it let us know!

[marcysutton]

We're taking this on internally, so stay tuned.

[laurieontech]

Closing this as the styling docs were updated with the blog 2.0 release.