paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 38 Packages Projects Releases Wiki Activity

docs: Improve guidelines docs & update links to MUI V4

Browse Source 
Signed-off-by: Carlos Esteban Lopez <lcarlosesteb@vmware.com>
This commit is contained in:
Carlos Esteban Lopez
2022-10-28 18:20:00 -05:00
parent d217290e1d
commit a24ae1e7a9
1 changed files with 49 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dls/component-design-guidelines.md
+49 -42
View File
@@ -6,8 +6,8 @@ description: Documentation on Design
Be it a new component contribution, or plugin specific components, you'll want
to follow these guidelines. We'll cover the three main subjects that define the
general look and feel of your components, all of which build on top of the Material-UI
theme features:
general look and feel of your components, all of which build on top of the
Material-UI theme features:
- Layout
- Color palette
@@ -19,10 +19,11 @@ Layout refers to how you organize or stack content. Whenever possible, we want
to use Backstage's components (check the [Storybook][1] for a list and demo)
first, and otherwise fall back to Material-UI components (check the [MUI docs][2]).
If none of these fit your layout needs, then you can build your own components. However, using
HTML+CSS directly is not recommended, it's better to use MUI layout components
to make your layout theme aware, meaning if someone changes the theme, your
layout would react to those changes without requiring updates to your code.
If none of these fit your layout needs, then you can build your own components.
However, using HTML+CSS directly is not recommended, it's better to use MUI
layout components to make your layout theme aware, meaning if someone changes
the theme, your layout would react to those changes without requiring updates
to your code.
Specifically you want to look at these components that make use of the
`theme.spacing()` function for margins, paddings and positions, as well as
@@ -30,19 +31,23 @@ color palette and typography:
- [Container][3] mostly at page level
- [Box][4] like a div that can be customized a lot
- [Grid][5] & [Grid V2][6] (preferable V2) for flexible grid layouts
- [Stack][7] for vertical layouts (single column)
- [Paper][8] The base of a card, like it's background & padding on the borders
- [Card][9] Card with support for title, description, buttons, images...
- [Grid][5] for flexible grid layouts
- [Paper][6] The base of a card, like it's background & padding on the borders
- [Card][7] Card with support for title, description, buttons, images...
## Color palette
Any component that needs a color to put in the styles should be using the
theme's color palette. Most Backstage components and all MUI components should
use the theme's color palette by default, so unless you need explicit control
on the color of a component (say when the component was designed to use the
primary color but you want to use the secondary), then the easiest way to access
the color palette is with [`useTheme` hook](https://mui.com/material-ui/customization/theming/#accessing-the-theme-in-a-component).
If you're using an existing component and want to tweak the colors it uses in
general in the whole application, you can use a [Custom Theme][10] to override
specific styles for that component, that includes paddings, margins and colors.
However when making a component from scratch you'll need to reference the theme
as much as possible, make sure to use the theme's color palette. Most Backstage
components and all MUI components should use the theme's color palette by default,
so unless you need explicit control on the color of a component (say when the
component was designed to use the primary color but you want to use the
secondary color instead), then the easiest way to access the color palette is
to [Override the Component Styles][11] as suggested by Backstage.
It's not a very common use case to override a theme color in a MUI component
but let's say you have a Paper component that highlights its content with a
@@ -50,30 +55,31 @@ different color for a side menu or something (usually you use the elevation,
but maybe the designer wanted a colorful app). You can use the theme like this:
```tsx
import { useTheme } from '@mui/material/styles';
import { makeStyles, Paper } from '@material-ui/core';
export function Sidebar() {
const theme = useTheme();
return (
<Paper
sx={{
backgroundColor: theme.palette.primary.main,
}}
>
Some children here
</Paper>
);
const useStyles = makeStyles((theme: Theme) => ({
sidebarPaper: {
backgroundColor: theme.palette.primary.main,
color: theme.palette.primary.contrastText,
},
}));
export function Sidebar({ children }) {
const { sidebarPaper } = useStyles();
return <Paper className={sidebarPaper}>{children}</Paper>;
}
```
Here is a link to the [Default Palette values][10] you can use, the tokens will be the same, what changes are the colors associated with those depending on
your app theme color palette.
Here is a link to the [Default Palette values][8] you can use, the tokens will
be the same, what changes are the colors associated with those depending on your
app theme color palette, there's also a [Default Theme Explorer][12] to look
which tokens you can use as reference from the compiled theme.
## Typography
Most of the time the components from MUI will use the `<Typography />` component
which will use the theme's typography properties like font family, size, weight
and appropriate color from the palette for the context of that component. This applies for example to
and appropriate color from the palette for the context of that component. This applies for example to
buttons that use white font color for contained buttons, or the respective color
passed on via props when not outlined for proper contrast (buttons in dark
theme adapt properly by using a dark font instead of white).
@@ -83,18 +89,19 @@ the text, like when the parent component is a layout one, you use typography
component instead of the HTML counterparts, usually used for titles and
paragraphs but it is valid for any type of text.
Check the [Typography docs][11] for information on how to install, use,
Check the [Typography docs][9] for information on how to install, use,
customize semantic elements and specially the recommendations about
accessibility.
[1]: http://backstage.io/storybook
[2]: https://mui.com/material-ui/getting-started/overview/
[3]: https://mui.com/material-ui/react-container/
[4]: https://mui.com/material-ui/react-box/
[5]: https://mui.com/material-ui/react-grid/
[6]: https://mui.com/material-ui/react-grid2/
[7]: https://mui.com/material-ui/react-stack/
[8]: https://mui.com/material-ui/react-paper/
[9]: https://mui.com/material-ui/react-card/
[10]: https://mui.com/material-ui/customization/palette/#default-values
[11]: https://mui.com/material-ui/react-typography
[2]: https://v4.mui.com/getting-started/supported-components/
[3]: https://v4.mui.com/components/container/
[4]: https://v4.mui.com/components/box/
[5]: https://v4.mui.com/components/grid/
[6]: https://v4.mui.com/components/paper/
[7]: https://v4.mui.com/components/cards/
[8]: https://v4.mui.com/customization/palette/#default-values
[9]: https://v4.mui.com/customization/typography/
[10]: https://backstage.io/docs/getting-started/app-custom-theme
[11]: https://backstage.io/docs/getting-started/app-custom-theme#overriding-backstage-and-material-ui-components-styles
[12]: https://v4.mui.com/customization/default-theme/#explore