docs(variants): Clearly explain variant notation

[lachlanjc]

At @erikdstock’s excellent suggestion, clarifying how the notation for accessing variants works.

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/systemui/theme-ui/fpgy38nht
✅ Preview: https://theme-ui-git-docs-variant-notation.systemui.vercel.app

[erikdstock]

Looks great! I'm not sure how useful any of this would be useful for documentation but I'd like to clarify - styles are applied and overridden in this order:

1. theme.styles.root: automatically applied from the body element
2. theme.styles.<tagName> for MDX or <Themed[tagName] / > or Styled.[tagname]` components
3. variants (probably best not to mix them):

• built-in variant prop for theme-ui/componentssx eg <Button variant="outline"
• sx prop variant key with full path eg <div sx={{variant: "buttons.outline"}}

4. sx prop styles
5. (maybe an anti-pattern) className manually passed down from custom parent components, eg

const CustomButton = ({ children, className }) => (
  <Button
    className={className}
    variant="primary"
    sx={{ borderColor: "purple" }}
  >
    {children} (but custom)
  </Button>
)

// sx is converted to className
<CustomButton sx={{p: 5}}>Big Button</ CustomButton>

Finally, within the theme-ui/components: variant prop, which may have its own special key/default (eg theme.buttons), using a full theme path with the dot is an option as well- eg <Button variant="secondary" is equivalent to variant="buttons.secondary" and <Button variant="cards.primary" or variant="styles.button" would also be permitted, if not advisable.

Example codesandbox

I'm also wondering if there are any identified anti-patterns - In the example above radical departures like adding link styles to a button don't seem to work, and I've also found that there is always a balance to strike as far as what belongs isolated in a theme file vs declared where it is used or where some defaults are applied.

Another thought i'd be willing to take on - it would be nice to add doc comments for default theme keys to the custom components.

[hasparus]

Great improvement, folks.

I'm approving both the current addition and any changes / more content based on Erik's comment.

[lachlanjc]

Thanks @erikdstock! I added a section about styles linking to various places those are used. I’m going to merge this now as I don’t want making this perfect to interfere with getting something better live, but we could definitely keep making this better. Appreciate the feedback as always.

[hasparus]

Hey @lachlanjc, I'm not sure if this bullet doesn't "conflict" with the last one.
BaseStyles is used to style embedded HTML content, but MDX is styled with Themed (i.e. ## maps to Themed.h2)

[lachlanjc]

Hmm. Using Next.js that's not the case (MDX is treated the same as HTML children, so you need BaseStyles), so I've never experienced that. I guess we can just remove the MDX reference for now?

[hasparus]

MDX is treated the same as HTML children

That MDXProvider rendered by our ThemeProvider doesn't work in Next? (We pass an object with components through context)

[lachlanjc]

Nope: #1130

[hasparus]

Doesn't a new version of MDX packages specified in resolutions solve that issue?

#1130 (comment)

[lachlanjc]

Perhaps! Forgot about that & have never tried it

[hasparus]

I guess we can just remove the MDX reference for now?

Yeah, this sound like a good idea :D

[lachlanjc]

fbb3451

[erikdstock]

Thanks yall, this is great!