[typescript] Illustrate issue with ambiguous css class names

docs/src/pages/guides/typescript/typescript.md

@@ -78,6 +78,52 @@ const styles = ({ palette, spacing }: Theme) => createStyles({
 
 `createStyles` is just the identity function; it doesn't "do anything" at runtime, just helps guide type inference at compile time.
 
+### Media queries
+
+`withStyles` allows a styles object with top level media-queries like so:
+
+```ts
+const styles = createStyles({
+  root: {
+    minHeight: '100vh',
+  },
+  '@media (min-width: 960px)': {
+    root: {
+      display: 'flex',
+    },
+  },
+});
+```
+
+However to allow these styles to pass TypeScript the definitions have to be ambiguous concerning names for CSS classes and actual CSS property names. Due to this class names that are equal to CSS properties should be avoided.
+
+```ts
+// error because TypeScript thinks `@media (min-width: 960px)` is a class name
+// and `content` is the css property
+const ambiguousStyles = createStyles({
+  content: {
+    minHeight: '100vh',
+  },
+  '@media (min-width: 960px)': {
+    content: {
+      display: 'flex',
+    },
+  },
+});
+
+// works just fine
+const ambiguousStyles = createStyles({
+  contentClass: {
+    minHeight: '100vh',
+  },
+  '@media (min-width: 960px)': {
+    contentClass: {
+      display: 'flex',
+    },
+  },
+});
+```
+
 ### Augmenting your props using `WithStyles`
 
 Since a component decorated with `withStyles(styles)` gets a special `classes` prop injected, you will want to define its props accordingly:

packages/material-ui/test/typescript/styles.spec.tsx

@@ -238,6 +238,35 @@ withStyles(theme =>
   }),
 );
 
+{
+  // allow top level media queries
+  // https://github.com/mui-org/material-ui/issues/12277
+
+  // typescript thinks `content` is the CSS property not a classname
+  // $ExpectError
+  const ambiguousStyles = createStyles({
+    content: {
+      minHeight: '100vh',
+    },
+    '@media (min-width: 960px)': {
+      content: {
+        display: 'flex',
+      },
+    },
+  });
+
+  const styles = createStyles({
+    contentClass: {
+      minHeight: '100vh',
+    },
+    '@media (min-width: 960px)': {
+      contentClass: {
+        display: 'flex',
+      },
+    },
+  });
+}
+
 {
   const styles = (theme: Theme) =>
     createStyles({