MUI best practices
This article assumes you're following our recommended practice by using our Material UI theme. Following the steps below maximises compatibility with Docker Desktop and minimises the work you need to do as an extension author. They should be considered supplementary to the non-MUI-specific guidelines found in the UI Styling overview.
Assume the theme can change at any time
Resist the temptation to fine-tune your UI with precise colors, offsets and font sizings to make it look as attractive as possible. Any specializations you make today will be relative to the current MUI theme, and may look worse when the theme changes. Any part of the theme might change without warning, including (but not limited to):
- The font, or font sizes
- Border thicknesses or styles
- Colors:
- Our palette members (e.g.
red-100
) could change their RGB values - The semantic colors (e.g.
error
,primary
,textPrimary
, etc) could be changed to use a different member of our palette - Background colors (e.g. those of the page, or of dialogs) could change
- Our palette members (e.g.
- Spacings:
- The size of the basic unit of spacing,(exposed via
theme.spacing
. For instance, we may allow users to customize the density of the UI - The default spacing between paragraphs or grid items
- The size of the basic unit of spacing,(exposed via
The best way to build your UI, so that it’s robust against future theming changes, is to:
- Override the default styling as little as possible.
- Use semantic typography. e.g. use
Typography
s orLink
s with appropriatevariant
s instead of using typographical HTML elements (<a>
,<p>
,<h1>
, etc) directly. - Use canned sizes. e.g. use
size="small"
on buttons, orfontSize="small"
on icons, instead of specifying sizes in pixels. - Prefer semantic colors. e.g. use
error
orprimary
over explicit color codes. - Write as little CSS as possible. Write semantic markup instead. For example, if you want to space out paragraphs of text, use the
paragraph
prop on yourTypography
instances. If you want to space out something else, use aStack
orGrid
with the default spacing. - Use visual idioms you’ve seen in the Docker Desktop UI, since these are the main ones we’ll test any theme changes against.
When you go custom, centralize it
Sometimes you’ll need a piece of UI that doesn’t exist in our design system. If so, we recommend that you first reach out to us. We may already have something in our internal design system, or we may be able to expand our design system to accommodate your use case.
If you still decide to build it yourself after contacting us, try and define the new UI in a reuseable fashion. If you define your custom UI in just one place, it’ll make it easier to change in the future if our core theme changes. You could use:
- A new
variant
of an existing component - see MUI docs - A MUI mixin (a freeform bundle of reuseable styling rules defined inside a theme)
- A new reuseable component
Some of the above options require you to extend our MUI theme. See the MUI documentation on theme composition.
What's next?
- Take a look at our UI styling guide.
- Learn how to publish your extension.