From c7b582195b047b5daff2249ca37def975a7bdf8a Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Thu, 20 Oct 2022 17:52:56 -0500 Subject: [PATCH] docs: Add component design guidelines Signed-off-by: Carlos Esteban Lopez --- docs/dls/component-design-guidelines.md | 100 ++++++++++++++++++++++++ microsite/sidebars.json | 1 + mkdocs.yml | 1 + 3 files changed, 102 insertions(+) create mode 100644 docs/dls/component-design-guidelines.md diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md new file mode 100644 index 0000000000..3d907d7dec --- /dev/null +++ b/docs/dls/component-design-guidelines.md @@ -0,0 +1,100 @@ +--- +id: design +title: Design +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 3 main subjects that define the +general look and feel of your components, all of which build on top of the MUI +theme features: + +- Layout +- Color palette +- Typography + +## 🏗️ Layout + +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) +or MUI components (check the [MUI docs][2]). + +If none of these fit your layout needs, then you can build one, 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 +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... + +## 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 design to use the +primay 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). + +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 it's content with a +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'; + +export function Sidebar() { + const theme = useTheme(); + return ( + + Some children here + + ); +} +``` + +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. + +## Typography + +Most of the time the components from MUI will use the `` 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, like +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). + +However for those cases where the parent component of the content doesn't handle +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, +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 diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 0826541071..dadcd6c3db 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -314,6 +314,7 @@ ], "Designing for Backstage": [ "dls/design", + "dls/component-design-guidelines", "dls/contributing-to-storybook", "dls/figma" ], diff --git a/mkdocs.yml b/mkdocs.yml index 36ff1c6348..7372e46a06 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -176,6 +176,7 @@ nav: - Heroku: 'deployment/heroku.md' - Designing for Backstage: - Design: 'dls/design.md' + - Component Design Guidelines: 'dls/component-design-guidelines.md' - Contributing to Storybook: 'dls/contributing-to-storybook.md' - Figma: 'dls/figma.md' - API Reference: