[docs] Improve documentation of the system

docs/pages/system/sx.js

@@ -0,0 +1,20 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'system/sx';
+const requireDemo = require.context('docs/src/pages/system/sx', false, /\.(js|tsx)$/);
+const requireRaw = require.context(
+  '!raw-loader!../../src/pages/system/sx',
+  false,
+  /\.(js|md|tsx)$/,
+);
+
+export default function Page({ demos, docs }) {
+  return <MarkdownDocs demos={demos} docs={docs} requireDemo={requireDemo} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/src/pages.js

@@ -174,6 +174,7 @@ const pages = [
   {
     pathname: '/system',
     children: [
+      { pathname: '/system/sx' },
       { pathname: '/system/basics' },
       { pathname: '/system/borders' },
       { pathname: '/system/display' },

docs/src/pages/system/sx/BreakpointsAsArray.js

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function BreakpointsAsArray() {
+  return (
+    <Box
+      sx={{
+        width: [100, 200, 300, 400, 500],
+      }}
+    >
+      This box has a responsive width
+    </Box>
+  );
+}

docs/src/pages/system/sx/BreakpointsAsArray.tsx

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function BreakpointsAsArray() {
+  return (
+    <Box
+      sx={{
+        width: [100, 200, 300, 400, 500],
+      }}
+    >
+      This box has a responsive width
+    </Box>
+  );
+}

docs/src/pages/system/sx/BreakpointsAsObject.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function BreakpointsAsObject() {
+  return (
+    <Box
+      sx={{
+        width: {
+          sx: 100,
+          sm: 200,
+          md: 300,
+          lg: 400,
+          xl: 500,
+        },
+      }}
+    >
+      This box has a responsive width
+    </Box>
+  );
+}

docs/src/pages/system/sx/BreakpointsAsObject.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function BreakpointsAsObject() {
+  return (
+    <Box
+      sx={{
+        width: {
+          sx: 100,
+          sm: 200,
+          md: 300,
+          lg: 400,
+          xl: 500,
+        },
+      }}
+    >
+      This box has a responsive width
+    </Box>
+  );
+}

docs/src/pages/system/sx/GettingStarted.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function GettingStarted() {
+  return (
+    <Box
+      sx={{
+        p: 3,
+        color: 'primary.main',
+        boxShadow: 3,
+        ':hover': {
+          backgroundColor: 'primary.light',
+          color: 'white',
+        },
+      }}
+    >
+      How to use the sx prop
+    </Box>
+  );
+}

docs/src/pages/system/sx/GettingStarted.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function GettingStarted() {
+  return (
+    <Box
+      sx={{
+        p: 3,
+        color: 'primary.main',
+        boxShadow: 3,
+        ':hover': {
+          backgroundColor: 'primary.light',
+          color: 'white',
+        },
+      }}
+    >
+      How to use the sx prop
+    </Box>
+  );
+}

docs/src/pages/system/sx/ValueAsFunction.js

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+
+export default function ValueAsFunction() {
+  return (
+    <Box
+      sx={{
+        p: 1,
+        border: 1,
+        borderColor: (theme) => theme.palette.primary.main,
+      }}
+    >
+      Border color with theme value
+    </Box>
+  );
+}

docs/src/pages/system/sx/ValueAsFunction.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+import { Theme } from '@material-ui/core/styles';
+
+export default function ValueAsFunction() {
+  return (
+    <Box
+      sx={{
+        p: 1,
+        border: 1,
+        borderColor: (theme: Theme) => theme.palette.primary.main,
+      }}
+    >
+      Border color with theme value
+    </Box>
+  );
+}

docs/src/pages/system/sx/sx.md

@@ -0,0 +1,92 @@
+# The `sx` prop
+
+<p class="description">Utility for styling elements inline, using the theme values.</p>
+
+## Getting Started
+
+Each `@material-ui/core` component supports the `sx` prop. The prop is a superset of CSS, that let's you add any CSS to the underlaying component, while mapping values to different theme keys. This should help you to keep your application look consistent.
+
+We recommend you use this prop whenever you need to add one-of style overrides on the Material-UI components. If you repetedly add the same styles on some component, than the `styled()` is better alternative, as it allows you to specify the overrides only ones and reuse them in all component instances.
+
+{{"demo": "pages/system/sx/GettingStarted.js", "defaultCodeOpen": true}}
+
+# Property to theme key mapping
+
+You can explore the [System API](system/api/) page to discover how the different css (and custom) properties are mapped to the theme keys.
+
+# Value as function
+
+If you wish to use the theme for some css property that is not supported by the system, you can use function as a value, where you can have access to the theme object.
+
+{{"demo": "pages/system/sx/ValueAsFunction.js", "defaultCodeOpen": true}}
+
+# Breakpoints
+
+If you would like to have responsive values for some CSS property, you may use the breakpoints shorthand syntax. We offer two ways of defining the breakpoints:
+
+## Breakpoints as array
+
+The first option is to define your breakpoints as an array, from the smallest to the largest breakpoint.
+
+{{"demo": "pages/system/sx/BreakpointsAsArray.js", "defaultCodeOpen": true}}
+
+## Breakpoints as object
+
+The second option for defining breakpoints is to define them as object, using the breakpoints as keys. Here is an example of how you may define the previous example by using the object syntax.
+
+{{"demo": "pages/system/sx/BreakpointsAsObject.js", "defaultCodeOpen": true}}
+
+## Custom breakpoints
+
+You can also specify your own custom breakpoints and use them as keys when defining the breakpoints object. Here is an example of how to do that.
+
+```jsx
+import * as React from 'react';
+import Box from '@material-ui/core/Box';
+import { createMuiTheme, ThemeProvider } from '@material-ui/core/styles';
+
+const theme = createMuiTheme({
+  breakpoints: {
+    values: {
+      tablet: 640,
+      laptop: 1024,
+      desktop: 1280,
+    },
+  },
+});
+
+export default function CustomBreakpoints() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Box
+        sx={{
+          width: {
+            tablet: 100,
+            laptop: 300,
+            desktop: 500,
+          },
+        }}
+      >
+        This box has a responsive width
+      </Box>
+    </ThemeProvider>
+  );
+}
+```
+
+If you are using TypeScript, you would also need to use [module augmentation](/guides/typescript/#customization-of-theme) for the theme to accept the above values.
+
+```ts
+declare module '@material-ui/core/styles/createBreakpoints' {
+  interface BreakpointOverrides {
+    xs: false; // removes the `xs` breakpoint
+    sm: false;
+    md: false;
+    lg: false;
+    xl: false;
+    tablet: true; // adds the `tablet` breakpoint
+    laptop: true;
+    desktop: true;
+  }
+}
+```

docs/translations/translations.json

@@ -211,6 +211,7 @@
     "/styles/basics": "Basics",
     "/styles/advanced": "Advanced",
     "/system": "System",
+    "/system/sx": "Sx",
     "/system/basics": "Basics",
     "/system/borders": "Borders",
     "/system/display": "Display",