From c7b582195b047b5daff2249ca37def975a7bdf8a Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Thu, 20 Oct 2022 17:52:56 -0500 Subject: [PATCH 01/17] 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: From b4399355d569f78257224002269e22691e9d8ca3 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Fri, 21 Oct 2022 13:22:34 -0500 Subject: [PATCH 02/17] Update docs/dls/component-design-guidelines.md Co-authored-by: Phil Kuang Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 3d907d7dec..7c0f3e224b 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -40,7 +40,7 @@ color palette and typography: 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 +on the color of a component (say when the component was designed 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). From 1c8c0a2cc7153a3b610927cfcb1583f7f4fb4fee Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Fri, 21 Oct 2022 13:29:10 -0500 Subject: [PATCH 03/17] docs: Address PR comments Signed-off-by: Carlos Esteban Lopez --- .github/vale/Vocab/Backstage/accept.txt | 4 ++++ docs/dls/component-design-guidelines.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/vale/Vocab/Backstage/accept.txt b/.github/vale/Vocab/Backstage/accept.txt index 603d5fd9af..9ba2abbc78 100644 --- a/.github/vale/Vocab/Backstage/accept.txt +++ b/.github/vale/Vocab/Backstage/accept.txt @@ -219,6 +219,10 @@ onboarding Onboarding OpenShift orgs +padding +Padding +paddings +Paddings pagerduty pageview parallelization diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 7c0f3e224b..6b96e82ca0 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -42,7 +42,7 @@ 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 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). +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 From 56a74adc56338e198aa3e298b14383ddaa18d54d Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Fri, 21 Oct 2022 13:33:04 -0500 Subject: [PATCH 04/17] docs: Fix spelling issue Signed-off-by: Carlos Esteban Lopez --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 6b96e82ca0..3622d8f2ba 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -41,7 +41,7 @@ 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 -primay color but you want to use the secondary), then the easiest way to access +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). It's not a very common use case to override a theme color in a MUI component From dff521fd91b90cb8171968db55f27bb26b282b85 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Fri, 21 Oct 2022 17:59:28 -0500 Subject: [PATCH 05/17] docs: Fix document ID & title Signed-off-by: Carlos Esteban Lopez --- docs/dls/component-design-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 3622d8f2ba..f03fbea1fb 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -1,6 +1,6 @@ --- -id: design -title: Design +id: component-design-guidelines +title: Component Design Guidelines description: Documentation on Design --- From a46a72ac23c1a28437e4eb8f30cd3a6948a396c5 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:09:49 -0500 Subject: [PATCH 06/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index f03fbea1fb..520283ed84 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -5,7 +5,7 @@ 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 +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 MUI theme features: From 9dddc98de561bfce78b3bb19e1a002805f1fb0c5 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:10:09 -0500 Subject: [PATCH 07/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 520283ed84..257e32925c 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -6,7 +6,7 @@ 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 MUI +general look and feel of your components, all of which build on top of the Material-UI theme features: - Layout From e47357dedc82ac1016b769ad53e0fa66fbb0ee5b Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:10:18 -0500 Subject: [PATCH 08/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 257e32925c..8cc7624b11 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -15,7 +15,7 @@ theme features: ## 🏗️ Layout -Layout refers to how you organize or stack content, whenever possible we want +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]). From 33ee80aba6dc95a2cf4f1e173147f7527213369e Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:10:28 -0500 Subject: [PATCH 09/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 8cc7624b11..654f6fbbd2 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -17,7 +17,7 @@ theme features: 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]). +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 one, however using HTML+CSS directly is not recommended, it's better to use MUI layout components From 5c49a73041ea1133b4108482706a1eab02fa238c Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:10:39 -0500 Subject: [PATCH 10/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 654f6fbbd2..a396642c0b 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -45,7 +45,7 @@ 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). 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 +but let's say you have a Paper component that highlights its 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: From d4e4e45437e5c9e1d39aa3a363fa572166a0f3cd Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:10:48 -0500 Subject: [PATCH 11/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index a396642c0b..52f078ea12 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -47,7 +47,7 @@ the color palette is with [`useTheme` hook](https://mui.com/material-ui/customiz 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 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: +but maybe the designer wanted a colorful app). You can use the theme like this: ```tsx import { useTheme } from '@mui/material/styles'; From 8c46fedd36dcde5922e1b46c4304caf15eba60e6 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:11:53 -0500 Subject: [PATCH 12/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 52f078ea12..b474ee79d1 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -73,7 +73,7 @@ your app theme color palette. 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 +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). From 606d4f5247ef5854ce4a3fe28774a9cfa3050d31 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:12:17 -0500 Subject: [PATCH 13/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index b474ee79d1..0ebe0caada 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -19,7 +19,7 @@ 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 one, however using +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. From 842b8a7b800c8d8d4c83384b05e336c856e06935 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Jaramillo Date: Thu, 27 Oct 2022 09:12:58 -0500 Subject: [PATCH 14/17] Update docs/dls/component-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fredrik Adelöw Signed-off-by: Carlos Esteban Lopez Jaramillo --- docs/dls/component-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 0ebe0caada..07f8b8f9a1 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -38,7 +38,7 @@ color palette and typography: ## 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 +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 From d217290e1d1e886027521727211a9a3bf7eb2a1c Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Thu, 27 Oct 2022 09:29:39 -0500 Subject: [PATCH 15/17] fix: Remove unnecessary capitalized duplicates in vocab whitelist Signed-off-by: Carlos Esteban Lopez --- .github/vale/Vocab/Backstage/accept.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/vale/Vocab/Backstage/accept.txt b/.github/vale/Vocab/Backstage/accept.txt index 9ba2abbc78..5c0a7bdc8d 100644 --- a/.github/vale/Vocab/Backstage/accept.txt +++ b/.github/vale/Vocab/Backstage/accept.txt @@ -220,9 +220,7 @@ Onboarding OpenShift orgs padding -Padding paddings -Paddings pagerduty pageview parallelization From a24ae1e7a930921477c4a9549a6a5a660a373e6c Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Fri, 28 Oct 2022 18:20:00 -0500 Subject: [PATCH 16/17] docs: Improve guidelines docs & update links to MUI V4 Signed-off-by: Carlos Esteban Lopez --- docs/dls/component-design-guidelines.md | 91 +++++++++++++------------ 1 file changed, 49 insertions(+), 42 deletions(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 07f8b8f9a1..877c224446 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -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 ( - - Some children here - - ); +const useStyles = makeStyles((theme: Theme) => ({ + sidebarPaper: { + backgroundColor: theme.palette.primary.main, + color: theme.palette.primary.contrastText, + }, +})); + +export function Sidebar({ children }) { + const { sidebarPaper } = useStyles(); + return {children}; } ``` -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 `` 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 From 6b2ad43a902d1b7eda529fdeaeba9d3c0a1cd5e5 Mon Sep 17 00:00:00 2001 From: Carlos Esteban Lopez Date: Fri, 28 Oct 2022 18:39:03 -0500 Subject: [PATCH 17/17] docs: Additional explanation & punctuation Signed-off-by: Carlos Esteban Lopez --- docs/dls/component-design-guidelines.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md index 877c224446..65eef4c057 100644 --- a/docs/dls/component-design-guidelines.md +++ b/docs/dls/component-design-guidelines.md @@ -20,7 +20,7 @@ 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 +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. @@ -50,9 +50,10 @@ 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 -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: +but let's say you have a custom Sidebar component with a Paper component that +highlights its 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 { makeStyles, Paper } from '@material-ui/core';