Do / Don't Component

[emplums]

This PR adds the Do / Don't example components. Three components are added:

• DoDontWrapper (name is kinda weird, suggestions welcome): wraps the Do and Dont examples and provides layout styles
• Do provides a green check icon and layout styles
• Dont provides a red X icon and layout styles

[vercel]

This pull request is automatically deployed with Now.
To access deployments, click Details below or on the icon next to each push.

Latest deployment for this branch: https://doctocat-git-do-dont.primer.now.sh

[colebemis]

Awesome 🔥 Just left a couple suggestions

[colebemis]

What if the API for Do/Dont looked something like this instead:

-<Do src="#">
-  Blah blah blah
- </Do>
+ <Do caption="Blah blah blah">
+   <img src="#" width="100%" />
+ </Do>

This would make the component more flexible. I can see it being useful to be able to render more than just imgs in the Do/Don't component.

[emplums]

I generally don't love passing in text content as props as it feels pretty awkward 🤔Especially since these captions have the potential to be long-ish in length. The other alternative would be to allow users to pass in both the img and Caption as children, but we have to apply the width and height properties to the img tag which means we'd need to do some cloning and editing of children which I generally try to avoid. I think it's fine to leave this minimal for now and if it starts causing issues we can rethink the API in the future

[colebemis]

I'm not sure we need this component. In the interest of having a "minimal api surface area," I think we should just show an example of how to wrap the Do and Dont components with a Flex component in the documentation.

[colebemis]

💡 Using the Grid component (instead of Flex) in the documentation example would probably be cleaner:

<Grid gridTemplateColumns={['1fr', '1fr', '1fr 1fr']} gridGap={3}>
  <Do>...</Do>
  <Dont>...</Dont>
</Grid>

This would allow us to remove the margin-right from the Do and Dont components.

[emplums]

ok!

[colebemis]

Suggested change

	The Do / Don't set of components is used for providing good & bad examples within documentation. These examples appear side by side on desktop, and vertically stacked on mobile.
	The `Do` and `Dont` components are used for providing good and bad examples within documentation.

^ I don't think they necessarily have to always be side by side on desktop. Here's an example, where they're stacked on desktop: https://primer.style/design/ui-patterns/messaging#full-width

[colebemis]

@emplums I think it would also be helpful to include some documentation on how to import the Do/Dont components in the MDX file:

import {Do, Dont} from '@primer/gatsby-theme-doctocat'

[broccolini]

Hi, I know this is already merged in order to meet training deadline, but this came up in yesterday's show and tell and I wanted to share some feedback.

For the documentation are goal is to make writing documentation as low friction as possible. We know that some content owners will likely make updates in the GitHub web UI rather than cloning, and are comfortable with mardkown, but not familiar with react. So we we design the api of the docs, we should be aiming for ease of use, which translates in places to making stronger assumptions and abstractions than we might do otherwise for Primer Components.

I think @emplums was heading down the right track with a wrapper, because the markup is going to look a little alien to others, and once you've imported one component, you can import another. The wrapper should account for the components showing side-by-side on desktop, and stacked on mobile.

<DoDont>
  <Do src="url">
    text caption
  </Do>
  <Dont src="url">
    text caption
  </Dont>
</Do

I also don't think we should account for using the Do and Dont components without each other. The point of using this component is to show a comparison between the wrong and the right way.

I know this locks us into something that is harder to undo later, but in this case I think it's the right call in order to make writing docs as easy as possible for the widest audience.