Basic ThemeProvider examples do not work

• The issue is present in the latest release.
• I have searched the issues of this repository and believe that this is not a duplicate.

Current Behavior 😯

The existing Theme Provider documentation is misleading. When following the first example there is no mention that the configuration is not actually valid for use with the standard Material UI components.

Expected Behavior 🤔

I should be able to extend the example to start adding components such as Paper and Table.

Steps to Reproduce 🕹

• Take the basic example at https://codesandbox.io/s/hu12l
• Wrap the DeepChild component in a Paper component
• Demo fails with theme.shadows is undefined.

https://codesandbox.io/s/material-demo-xxzs3?file=/demo.js

Context 🔦

I was getting started with using theme providers and they would seemingly break at random with obscure errors when I started using other components such as Table. Each time I would dutifully remove all the code I’d added and go back to the basic example that was working and start adding code again.

I repeated this several times before realising that the example doesn’t actually work and you need to perform some other step though its not obvious what step that is. I’ve been left to assume that I need to use createMuiTheme for all themes, even nested ones.

[eps1lon]

Since this section is about the standalone @material-ui/styles I would double down on the /core vs /core/styles separation.

The warning is enough. The issue is that the code mentions @material-ui/core. Everything else will be resolved once we drop @material-ui/styles.

[chilversc]

@tchmnn From my experience, most people don’t read, they copy & paste. The existing warning didn’t seem to be enough for @chilversc. I think that we can apply #20457 (comment) and close the issue.

Exactly, in my case it was an overload of new concepts, I hadn’t realised the context switch in the documentation and the separation between the two and thus wasn’t really understanding the warning. Even though I read it, it just didn’t make much sense at the time as in my mind I didn’t realise the documentation was now discussing a different module, so the context I had in my head was still material-ui since the topic in the navigation is sandwiched inside a list of other material-ui topics.