diff --git a/docs/src/pages/customization/css-in-js/css-in-js.md b/docs/src/pages/customization/css-in-js/css-in-js.md index 194416adae1bd9..a22b1c99866286 100644 --- a/docs/src/pages/customization/css-in-js/css-in-js.md +++ b/docs/src/pages/customization/css-in-js/css-in-js.md @@ -80,11 +80,16 @@ As well as the option to make the class names **deterministic** with the `danger - development: `.MuiAppBar-root` - production: `.MuiAppBar-root` -⚠️ **Be very cautious when using `dangerouslyUseGlobalCSS`.** -We provide this option as an escape hatch for quick prototyping, -but you should avoid relying on it for code running in production -as it's very hard to keep track of class name API changes. -Global CSS is inherently fragile. +⚠️ **Be cautious when using `dangerouslyUseGlobalCSS`.** +We provide this option as an escape hatch for quick prototyping. +Relying on it for code running in production has the following implications: +- Global CSS is inherently fragile. People use strict methodologies like [BEM](http://getbem.com/introduction/) to workaround the issue. +- It's harder to keep track of `classes` API changes. + +⚠️ When using `dangerouslyUseGlobalCSS` standalone (without Material-UI), you should name your style sheets. `withStyles` has a name option for that: +```jsx +const Button = withStyles(styles, { name: 'button' })(ButtonBase) +``` ## CSS injection order