diff --git a/.github/vale/Vocab/Backstage/accept.txt b/.github/vale/Vocab/Backstage/accept.txt
index 67213133dc..58f5b57004 100644
--- a/.github/vale/Vocab/Backstage/accept.txt
+++ b/.github/vale/Vocab/Backstage/accept.txt
@@ -234,6 +234,8 @@ onboarding
Onboarding
OpenShift
orgs
+padding
+paddings
pagerduty
pageview
parallelization
diff --git a/docs/dls/component-design-guidelines.md b/docs/dls/component-design-guidelines.md
new file mode 100644
index 0000000000..65eef4c057
--- /dev/null
+++ b/docs/dls/component-design-guidelines.md
@@ -0,0 +1,108 @@
+---
+id: component-design-guidelines
+title: Component Design Guidelines
+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:
+
+- 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)
+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.
+
+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] 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
+
+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 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';
+
+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][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
+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][9] for information on how to install, use,
+customize semantic elements and specially the recommendations about
+accessibility.
+
+[1]: http://backstage.io/storybook
+[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
diff --git a/microsite/sidebars.json b/microsite/sidebars.json
index f9fdb9ee9a..725290cb69 100644
--- a/microsite/sidebars.json
+++ b/microsite/sidebars.json
@@ -316,6 +316,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 ea2031dac6..f3194f0d61 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -178,6 +178,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: