Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Improve the documentation of the dark theme #19122

Merged
merged 13 commits into from
Jan 13, 2020
Merged

[docs] Improve the documentation of the dark theme #19122

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1aff23f
[docs] Make inspector aware of current theme
m4theushw Jan 7, 2020
67033d5
Add toggle to show dark theme values
m4theushw Jan 8, 2020
2f07fec
Add color swatches
m4theushw Jan 8, 2020
7ec1092
Remove unused import
m4theushw Jan 8, 2020
105c214
Add TypeScript demo
m4theushw Jan 8, 2020
d436fad
Add more colors and group names
m4theushw Jan 9, 2020
5041d6a
Minor tweaks
m4theushw Jan 9, 2020
c4544cc
Minor tweaks
m4theushw Jan 9, 2020
6d64407
Add missing space
m4theushw Jan 9, 2020
7ac20de
Remove mentions to 'palette.text.hint'
m4theushw Jan 9, 2020
fb7bcb7
Use default theme
m4theushw Jan 9, 2020
467807c
Use palette.divider color
m4theushw Jan 9, 2020
313505b
polishing
oliviertassinari Jan 10, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion docs/src/pages/customization/default-theme/DefaultTheme.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,7 @@ function DefaultTheme(props) {
const [checked, setChecked] = React.useState(false);
const [expandPaths, setExpandPaths] = React.useState(null);
const t = useSelector(state => state.options.t);
const [darkTheme, setDarkTheme] = React.useState(false);

React.useEffect(() => {
const URL = url.parse(document.location.href, true);
Expand All @@ -240,7 +241,9 @@ function DefaultTheme(props) {
);
}, []);

const data = React.useMemo(createMuiTheme, []);
const data = React.useMemo(() => {
return createMuiTheme({ palette: { type: darkTheme ? 'dark' : 'light' } });
}, [darkTheme]);

const allNodeIds = useNodeIdsLazy(data);
React.useDebugValue(allNodeIds);
Expand All @@ -266,6 +269,18 @@ function DefaultTheme(props) {
}
label={t('expandAll')}
/>
<FormControlLabel
className={classes.switch}
control={
<Switch
checked={darkTheme}
onChange={(event, newValue) => {
setDarkTheme(newValue);
}}
/>
}
label={t('useDarkTheme')}
/>
<Inspector data={data} expandPaths={expandPaths} expandLevel={checked ? 100 : 1} />
</div>
);
Expand Down
8 changes: 4 additions & 4 deletions docs/src/pages/customization/default-theme/default-theme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@

## Explore

Explore the documentation theme object:
Explore the default theme object:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have an impression of déjà vu, I wonder if we didn't iterate on this already in the past. If we did, it would be interesting to see the discussion we had.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had the same feeling (and had a quick look at git blame to try to find a related PR/issue, without any luck). As it stands, we show the default theme, so that's what we should document in the markdown.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 years ago: #9857. It seems that we still didn't find a good approach.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good find. Option 2 from the previous list - aligning the default theme and docs colors is the next move for v5, as already tentatively agreed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so we move forward like this?

Copy link
Member

@oliviertassinari oliviertassinari Jan 11, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about we change the default theme colors in a minor?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a relatively low impact change – it won't actually break anything, and if a site isn't customising even the theme basics, it might not matter much to them; but IMHO it would break expectations to change this in a minor – to me, a visually breaking change is still a breaking change.

Combined with the fact that this has been a low priority for a long time without any significant pushback, I suggest that we put it on hold, but with a clear plan to address it in v5.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure


{{"demo": "pages/customization/default-theme/DefaultTheme.js", "hideHeader": true}}

> Tip: you can play with the documentation theme object in **your console**,
as the `theme` variable is exposed on all the documentation pages.
Please note that the documentation site is using a custom theme.
> Tip: you can play with the documentation theme object in your browser console,
> as the `theme` variable is exposed on all the documentation pages.
> Please note that **the documentation site is using a custom theme**.

If you want to learn more about how the theme is assembled, take a look at [`material-ui/style/createMuiTheme.js`](https://github.com/mui-org/material-ui/blob/master/packages/material-ui/src/styles/createMuiTheme.js),
and the related imports which `createMuiTheme` uses.
78 changes: 75 additions & 3 deletions docs/src/pages/customization/palette/DarkTheme.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,23 +1,95 @@
import React from 'react';
import Typography from '@material-ui/core/Typography';
import Paper from '@material-ui/core/Paper';
import Grid from '@material-ui/core/Grid';
import { makeStyles, ThemeProvider, useTheme, createMuiTheme } from '@material-ui/core/styles';

const useStyles = makeStyles(theme => ({
root: {
padding: theme.spacing(3),
textAlign: 'center',
backgroundColor: theme.palette.background.default,
color: theme.palette.text.primary,
overflow: 'auto',
[theme.breakpoints.up('md')]: {
padding: theme.spacing(3),
},
},
paper: {
padding: theme.spacing(3),
},
color: {
display: 'flex',
alignItems: 'center',
'& div:first-of-type': {
width: theme.spacing(6),
height: theme.spacing(6),
marginRight: theme.spacing(1),
borderRadius: theme.shape.borderRadius,
},
},
group: {
marginTop: theme.spacing(3),
},
}));

function Demo() {
const classes = useStyles();
const theme = useTheme();

const item = (color, name, expanded = false, border = false) => (
<Grid item xs={12} md={expanded ? 8 : 4} className={classes.color}>
<div
style={{
backgroundColor: color,
border: border ? `1px solid ${theme.palette.divider}` : undefined,
}}
/>
<div>
<Typography variant="body2">{name}</Typography>
<Typography variant="body2" color="textSecondary">
{color}
</Typography>
</div>
</Grid>
);

return (
<div className={classes.root}>
<Typography>{`${theme.palette.type} theme`}</Typography>
<Paper className={classes.paper}>
<Typography gutterBottom>Typography</Typography>
<Grid container spacing={2}>
{item(theme.palette.text.primary, 'palette.text.primary')}
{item(theme.palette.text.secondary, 'palette.text.secondary')}
{item(theme.palette.text.disabled, 'palette.text.disabled')}
</Grid>
<Grid container spacing={2}>
{item(theme.palette.text.hint, 'palette.text.hint')}
</Grid>
<Typography gutterBottom className={classes.group}>
Buttons
</Typography>
<Grid container spacing={2}>
{item(theme.palette.action.active, 'palette.action.active')}
{item(theme.palette.action.hover, 'palette.action.hover')}
{item(theme.palette.action.selected, 'palette.action.selected')}
</Grid>
<Grid container spacing={2}>
{item(theme.palette.action.disabled, 'palette.action.disabled')}
{item(theme.palette.action.disabledBackground, 'palette.action.disabledBackground', true)}
</Grid>
<Typography gutterBottom className={classes.group}>
Background
</Typography>
<Grid container spacing={2}>
{item(theme.palette.background.default, 'palette.background.default', false)}
{item(theme.palette.background.paper, 'palette.background.paper', false, true)}
</Grid>
<Typography gutterBottom className={classes.group}>
Divider
</Typography>
<Grid container spacing={2}>
{item(theme.palette.divider, 'palette.divider')}
</Grid>
</Paper>
</div>
);
}
Expand Down
83 changes: 80 additions & 3 deletions docs/src/pages/customization/palette/DarkTheme.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import React from 'react';
import Typography from '@material-ui/core/Typography';
import Paper from '@material-ui/core/Paper';
import Grid from '@material-ui/core/Grid';
import {
createStyles,
makeStyles,
Expand All @@ -12,10 +14,28 @@ import {
const useStyles = makeStyles((theme: Theme) =>
createStyles({
root: {
padding: theme.spacing(3),
textAlign: 'center',
backgroundColor: theme.palette.background.default,
color: theme.palette.text.primary,
overflow: 'auto',
[theme.breakpoints.up('md')]: {
padding: theme.spacing(3),
},
},
paper: {
padding: theme.spacing(3),
},
color: {
display: 'flex',
alignItems: 'center',
'& div:first-of-type': {
width: theme.spacing(6),
height: theme.spacing(6),
marginRight: theme.spacing(1),
borderRadius: theme.shape.borderRadius,
},
},
group: {
marginTop: theme.spacing(3),
},
}),
);
Expand All @@ -24,9 +44,66 @@ function Demo() {
const classes = useStyles();
const theme = useTheme();

const item = (
color: string,
name: string,
expanded: boolean = false,
border: boolean = false,
) => (
<Grid item xs={12} md={expanded ? 8 : 4} className={classes.color}>
<div
style={{
backgroundColor: color,
border: border ? `1px solid ${theme.palette.divider}` : undefined,
}}
/>
<div>
<Typography variant="body2">{name}</Typography>
<Typography variant="body2" color="textSecondary">
{color}
</Typography>
</div>
</Grid>
);

return (
<div className={classes.root}>
<Typography>{`${theme.palette.type} theme`}</Typography>
<Paper className={classes.paper}>
<Typography gutterBottom>Typography</Typography>
<Grid container spacing={2}>
{item(theme.palette.text.primary, 'palette.text.primary')}
{item(theme.palette.text.secondary, 'palette.text.secondary')}
{item(theme.palette.text.disabled, 'palette.text.disabled')}
</Grid>
<Grid container spacing={2}>
{item(theme.palette.text.hint, 'palette.text.hint')}
</Grid>
<Typography gutterBottom className={classes.group}>
Buttons
</Typography>
<Grid container spacing={2}>
{item(theme.palette.action.active, 'palette.action.active')}
{item(theme.palette.action.hover, 'palette.action.hover')}
{item(theme.palette.action.selected, 'palette.action.selected')}
</Grid>
<Grid container spacing={2}>
{item(theme.palette.action.disabled, 'palette.action.disabled')}
{item(theme.palette.action.disabledBackground, 'palette.action.disabledBackground', true)}
</Grid>
<Typography gutterBottom className={classes.group}>
Background
</Typography>
<Grid container spacing={2}>
{item(theme.palette.background.default, 'palette.background.default', false)}
{item(theme.palette.background.paper, 'palette.background.paper', false, true)}
</Grid>
<Typography gutterBottom className={classes.group}>
Divider
</Typography>
<Grid container spacing={2}>
{item(theme.palette.divider, 'palette.divider')}
</Grid>
</Paper>
</div>
);
}
Expand Down
4 changes: 2 additions & 2 deletions docs/src/pages/customization/palette/Intentions.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import React from 'react';
import Grid from '@material-ui/core/Grid';
import Typography from '@material-ui/core/Typography';
import { makeStyles, useTheme, rgbToHex } from '@material-ui/core/styles';
import { makeStyles, createMuiTheme, rgbToHex } from '@material-ui/core/styles';

const useStyles = makeStyles(theme => ({
root: {
Expand All @@ -25,7 +25,7 @@ const useStyles = makeStyles(theme => ({

export default function Intentions() {
const classes = useStyles();
const theme = useTheme();
const theme = createMuiTheme();

const item = (color, name) => (
<Grid item xs={6} sm={4} className={classes.color}>
Expand Down
10 changes: 8 additions & 2 deletions docs/src/pages/customization/palette/Intentions.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
import React from 'react';
import Grid from '@material-ui/core/Grid';
import Typography from '@material-ui/core/Typography';
import { createStyles, makeStyles, Theme, useTheme, rgbToHex } from '@material-ui/core/styles';
import {
createStyles,
makeStyles,
Theme,
createMuiTheme,
rgbToHex,
} from '@material-ui/core/styles';

const useStyles = makeStyles((theme: Theme) =>
createStyles({
Expand All @@ -27,7 +33,7 @@ const useStyles = makeStyles((theme: Theme) =>

export default function Intentions() {
const classes = useStyles();
const theme = useTheme();
const theme = createMuiTheme();

const item = (color: string, name: string) => (
<Grid item xs={6} sm={4} className={classes.color}>
Expand Down
12 changes: 7 additions & 5 deletions docs/src/pages/customization/palette/palette.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ and the un-prefixed shades for the other intentions.

If you want to learn more about color, you can check out [the color section](/customization/color/).

{{"demo": "pages/customization/palette/Intentions.js", "bg": "inline"}}
{{"demo": "pages/customization/palette/Intentions.js", "bg": "inline", "hideHeader": true}}

### Customization

Expand All @@ -41,7 +41,7 @@ interface PaletteIntention {
main: string;
dark?: string;
contrastText?: string;
};
}
```

**Using a color object**
Expand Down Expand Up @@ -97,9 +97,9 @@ As in the example above, if the intention object contains custom colors using an
"main", "light", "dark" or "contrastText" keys, these map as follows:

- If the "dark" and / or "light" keys are omitted, their value(s) will be calculated from "main",
according to the "tonalOffset" value.
according to the "tonalOffset" value.
- If "contrastText" is omitted, its value will be calculated to contrast with "main",
according to the"contrastThreshold" value.
according to the"contrastThreshold" value.
m4theushw marked this conversation as resolved.
Show resolved Hide resolved

Both the "tonalOffset" and "contrastThreshold" values may be customized as needed.
A higher value for "tonalOffset" will make calculated values for "light" lighter, and "dark" darker.
Expand Down Expand Up @@ -130,7 +130,9 @@ const darkTheme = createMuiTheme({
});
```

{{"demo": "pages/customization/palette/DarkTheme.js", "bg": "inline", "defaultCodeOpen": false}}
The colors modified by the palette type are the following:

{{"demo": "pages/customization/palette/DarkTheme.js", "bg": "inline", "hideHeader": true}}

### User preference

Expand Down
1 change: 1 addition & 0 deletions docs/translations/translations.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"homeQuickWord": "A quick word from our sponsors:",
"helpToTranslate": "Help to translate",
"editWebsiteColors": "Edit website colors",
"useDarkTheme": "Use dark theme",
"toggleTheme": "Toggle light/dark theme",
"toggleRTL": "Toggle right-to-left/left-to-right",
"github": "GitHub repository",
Expand Down