[docs][workflows] Working with Style Libraries and Components

[marcysutton]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to style my site with libraries and components.

Evaluation

[Change emoji below based on your evaluation.]

Search	Discover	Complete	Linked	Tone	Style	Overall
😞	😞	😐	😐	😐	😄	😐

Steps taken to implement

Searchability

• Google search for "Gatsby js bootstrap" 😞

  • The first two results are community starters, then a mix of third-party blogs, and a closed GitHub issue on Bootstrap and jQuery.

• Google search for "Gatsby style libraries" 😞

  • The first two results are Gatsby official styling docs, including a mention of third-party libraries for CSS-in-JS but nothing very relevant on the first result.

• Google search for "Gatsby component libraries" 😄

  • Better results than style libraries and bootstrap, with the top 4 results being Gatsby official docs: Creating Component Libraries, Building with Components, CSS Libraries and Frameworks, and Adding React Components. The 5th result is a closed GitHub issue on Gatsby Component Library recommendations with an eye toward performance.
  • Creating Component Libraries isn't a how-to doc, but more of a conceptual post about best practices for tooling and setups, and high-level versioning information. A new doc on Making Reusable Components could mention component libraries and this doc could link to that.

Discoverability

• Search gatsbyjs.org for "style libraries" 😞

  • The top 3 results are Theme styling blog posts, one docs result for Enhancing with CSS-in-JS, and an unsorted result for an orphan Global Styles doc that needs to be integrated into a doc listed into the sidebar and/or removed.

• Go to gatsbyjs.org/docs to find style library documentation 😐

  • Look through Sidebar, click on "Reference Guides". See "Styling Your Site", and child overview page of "CSS Libraries and Frameworks"

• Search gatsbyjs.org for "bootstrap" or "bootstrap css" 😞

  • All results are related to the Bootstrap phase of Gatsby lifecycle APIs and a tutorial on Building Themes, and nothing to do with style libraries.

• Go to gatsbyjs.org/docs to find component library documentation 😐

  • Look through Sidebar Reference Guides, see "Adding Components to Markdown with MDX". No mention of component libraries or third-party components.
  • Look through Sidebar Reference Guides, see "Adding App and Website Functionality" and "Adding React Components" doc, which includes importing third-party components including material-ui and information on window/document gotchas.

• Search gatsbyjs.org for "component libraries" 😐

  • Results include 3-4 mentions in the same Creating Component Libraries doc, and Challenge 4 from 100 Days of Gatsby on adding a form component to your site (which specifically does not tell you how to do it, because it's part of a challenge).

Completeness

• On Adding React Components, there is great information about installing third-party components and gotchas with the build process and browser APIs. But the material-ui example is used without much context, and it doesn't mention the related Gatsby plugin that helps with a Flash of Unstyled Content.

  • The intro sentence essentially restates the page title, without offering more context on why you'd want to add React components.

• On CSS Libraries and Frameworks, Gatsby learners may be looking for other libraries that aren't listed so some coverage would help them in their discovery process.

• On Adding Components to Markdown with MDX, users may be trying to understand how to import components but there isn't obvious information for that.

  • Having instructions on how to use relative imports vs. libraries would be very helpful, even if we link off to more a canonical doc that can be referenced from other sections.

Linkedness

• On CSS Libraries and Frameworks, the links are limited to the resources with full reference guides. Having a catch-all "other frameworks" page could help provide more information and a curated list of third-party components.
• On Adding React Components, the only links present are on Porting from Create React App and Debugging HTML Builds.

Tone and accessibility

• CSS Libraries and Frameworks is short but friendly and appropriate for an Overview guide.
• Adding React Components meets requirements for tone and accessibility

Style

• Adding React Components has a reference to UK English ("favour") and needs to be updated to match the Gatsby Style Guide

Recommendations

• Update Adding React Components ([docs] Update Adding React Components #21284)
  • Add the phrase "component libraries" to so that page comes up in search
  • Fix style-guide issues for UK English (e.g. "favour")
  • Change the third-party component example to reference index.jsx to eliminate a step (creating a page called my-page.jsx
  • Document usage of the gatsby-plugin-material-ui as a third-party plugin to prevent a Flash of Unstyled Content
• Add a section or page to the MDX docs section on using third-party components (docs(workflows): new guide about importing and using components in MDX #21285)
• Add a new Reference Guide for Other Libraries and mention Bootstrap (including how to use the optional JS code which includes jQuery), Material UI, Reach UI, Grommet, etc. ([docs][guides] Other CSS Frameworks and Libraries page #21541)
• Add the phrase "style libraries" to the CSS Libraries & Frameworks overview page
• Add a new Reference Guide for Making Reusable Components and link to it from the Creating Component Libraries doc. ([docs][guides] Conceptual guide on Reusable Code Patterns #21282)

Draft the docs

• Write docs, following the format listed in these resources:
  • Overview on contributing to documentation
  • Docs Templates
• Add new articles to the docs sidebar under its parent doc section.

[marcysutton]

We have separate issues (and one PR) opened for the remaining items, so I'm going to close this meta issue. Great work, @gatsbyjs/learning!