feat(using-gatsby-image): refresh design, switch to emotion

[fk]

Didn't have teh good internets for a couple of hours today, but a folder of unsplash.com images and just had touched on using-gatsby-image yesterday … so I decided to make some good use of the mostly offline dev time and revisit https://using-gatsby-image.gatsbyjs.org/.

Here's a video: https://www.dropbox.com/s/axq2zp8lna9y71y/using-gatsby-image.mov?dl=0

• refresh'n'Gatsby-fy 💜UI and layout
  • noteworthy: hopefully improve homepage UX on mobile
• move from glamor to emotion
• refactor most things to styled components
• switch to system font stack; images and video show Larsseit for nav and headlines which I've been playing around locally
• refactor layout and page components a little
• fix active navigation state (adjust to @reach/router)
• throw in header, nav, and main
• add Gatsby monogram linking to https://www.gatsbyjs.org/
• add "Docs" link to main navigation (pointing to https://www.gatsbyjs.org/packages/gatsby-image/)
• fancy bullet points for the homepage "Out of the box it…" list
• "Documentation" block at the bottom of every page
  • add link to https://www.gatsbyjs.org/docs/using-gatsby-image/
• replace a couple of great unsplash.com images with a bunch of other great unsplash.com images ;)
• fetch all but one image from unsplash.com, removing a ton of data from the repo thanks to @DSchau (feat(examples): add a remote-images plugin so as to not introduce bloat #9605) 🎉

Todo:

• Fix image credits (<img title>)
• Optimize image query width/maxWidth
• Refactor CSS to template literals…

/cc @gatsbyjs/website

[jlengstorf]

This looks amazing, @fk!

A couple things noted inline that I'd like to see cleaned up for consistency and to drive a "Gatsby standard" of coding.

Also, a lot of these new images are huge — I'm not sure we want to put an additional 30MB of images into the repo for people to download. Maybe we can reduce the raw images down to whatever the maximum size is to avoid the impact on the overall repo size?

Thanks for putting this together!

[jlengstorf]

We had a discussion about styling that landed on using the styled component approach for Emotion, meaning we'll want to refactor this to be:

const GatsbyImage = styled(Img)`
	margin-bottom: ${rhythm(options.blockMarginBottom * 2)};
	/* ... */
`;

[fk]

Yeah, followed that and already did use styled for stuff I had to touch, but not everywhere else (yet). Happy to do so consistently!

[jlengstorf]

Ah, I thought this was all new code.

I'll let @amberleyromo make the call about how much we should refactor. My vote would be to just knock it out while we're in here, but she's the final word on this.

[amberleyromo]

@fk I would say if you feel it won't take too long and you feel good about it, go ahead and do it. Would be nice to have it as a good standalone example of the code style, since www will be switched over incrementally.

If not, don't stress, we can decide where it fits into priorities.

[fk]

@jlengstorf Not all new, just a little realign :D (also FWIW not all images are new, I tried to balance out old/new amount (add one/delete one), and plan on still removing a bunch more)

@amberleyromo I'll give it a shot because I also want to use styled a little more. Btw.…already got annoyed a couple times having to name things again ;)

[jlengstorf]

Using the styled component approach will make this easier, too:

const Component = styled('div')`
	background-color: red;

	img {
		border-radius: 2px;
	}
`;

[KyleAMathews]

I wouldn't call that "easier", just different

[jlengstorf]

Sorry — "easier" is in reference to the syntax being less complex, but agreed that it's just different.

[amberleyromo]

Yeah I find it harder, honestly, but it's just because I'm not as familiar with it.

[DSchau]

Harder than the css prop? It's the same style object in both places, just hoisted in one example and using a prop in the other, right?

[greglobinski]

@fk First of all the page looks great ❤️

I support @jlengstorf with using emotion full syntax with tagged template literals #9377 (comment)

styled("div")`
...
`

There are a couple of ways to compose styles.

1. The css way

const baseStyle = css`
  flex-grow: 1;
  font-size: 0.85rem;
  margin: 0;
  color: ${colors.gray.lightCopy};
  padding: ${rhythm(0.5)} 0 0;
`
const Description = styled("p")`
  ${baseStyle};
  color: red;

2. Re-styling components way

const Description = styled("p")`
  flex-grow: 1;
  font-size: 0.85rem;
  margin: 0;
  color: ${colors.gray.lightCopy};
  padding: ${rhythm(0.5)} 0 0;
`

const DescriptionBig = styled(DescriptionBase)`
  font-size: 2rem;
`

3. merging css classes with cx method
   https://emotion.sh/docs/cx

4. And of course using dynamic styles
   https://emotion.sh/docs/composition#composing-dynamic-styles

I think that we should prefer the fourth and the second methods choose which ways we prefer.

/cc @amberleyromo @jlengstorf @DSchau

[KyleAMathews]

@fk's point is those are all much less sophisticated than what you can do when styles are data not strings you're concatenating together.

[KyleAMathews]

You can make styles as strings work but it feels like a big step back imo

[greglobinski]

@KyleAMathews Sure, it could be that I do not spot some use cases when the objects work better.

[jlengstorf]

I think there are edge cases where styles work better, but overall moving to a JS abstraction over another language is a barrier for contributors who already know CSS.

My preference is to avoid logic in styles, and instead to have base styles that get extended where necessary:

const Button = styled('button')`
  background: red;
  border-radius: 0.5rem;
  color: white;
  font-size: 1.5rem;
`;

const BigButton = styled(Button)`
  font-size: 2.5rem;
`;

This makes it extremely clear that BigButton is an extension of Button, and doesn't require keeping how both JS and CSS work in your brain at the same time.

Conversely, the JS version looks less like styles and (for my brain) is significantly harder to parse whether it's logic for the UI or logic for the styles:

const Button = styled('button')(props => ({
  background: 'red',
  borderRadius: '0.5rem',
  color: 'white',
  fontSize: props.isBig ? '2.5rem' : '1.5rem',
}));

It's also less clear which button is being used in the second case, because the styles are now tied to the props and the result is hidden.

It's definitely going to come down to preference at the end of the day, but I feel pretty strongly that JS styles don't create enough benefit to justify the extra cognitive overhead.

[fk]

Maybe we can reduce the raw images down to whatever the maximum size is to avoid the impact on the overall repo size?

👍

[pieh]

Also, a lot of these new images are huge — I'm not sure we want to put an additional 30MB of images into the repo for people to download. Maybe we can reduce the raw images down to whatever the maximum size is to avoid the impact on the overall repo size?

How about creating unsplash source plugin? Or even just hardcoding urls to download images from unsplash for this example site?

[amberleyromo]

@pieh https://github.com/vacas5/gatsby-source-unsplash

[pieh]

@pieh vacas5/gatsby-source-unsplash

It doesn't actually download images (so we can process them) - it has urls to remote unsplash cdn ( https://github.com/vacas5/gatsby-source-unsplash/blob/master/gatsby-node.js )

[DSchau]

This looks great! As Jason said, images are probably going to be an issue--but otherwise this seems like a big improvement from a code & design perspective.

[DSchau]

I like this a lot!

[KyleAMathews]

We could write a little extension to source-airtable that uses createRemoteFileNode to pull down the actual image.

[KyleAMathews]

Extension in the site's gatsby-node.js and onCreateNode