Theming and CSS Structure
Relevant source files
The following files were used as context for generating this wiki page:- content/manuals/extensions/extensions-sdk/design/_index.md
- content/manuals/extensions/extensions-sdk/design/design-guidelines.md
- content/manuals/extensions/extensions-sdk/design/mui-best-practices.md
- content/contribute/style/formatting.md
- content/contribute/ui.md
- content/contribute/components/call-outs.md
- content/contribute/components/badges.md
The Docker documentation and extensions ecosystem prioritizes a consistent and accessible user experience that aligns with the visual identity of Docker Desktop. This is achieved through a defined design system, a recommended UI framework, and a set of best practices for styling and theming. The goal is to create a seamless experience for users, where extensions feel like an integrated part of the Docker Desktop application.
The styling approach is built on React and Material-UI (MUI), leveraging a specific Docker MUI theme to ensure visual consistency. This system supports both light and dark modes automatically and is designed to meet Level AA accessibility standards. For content authors and extension developers, adhering to these guidelines is crucial for both user experience and the official review process.
Sources: content/manuals/extensions/extensions-sdk/design/design-guidelines.md, content/manuals/extensions/extensions-sdk/design/_index.md
Core Styling Principles
The foundation of the UI/UX strategy is to create a consistent experience with Docker Desktop. This involves several key principles that developers must follow.
- Visual Consistency: Extensions should use the provided Docker Material UI Theme and follow the Docker Extensions Styleguide to match the look and feel of Docker Desktop.
- Light and Dark Themes: Extensions must support both light and dark themes. Using the recommended theme components ensures this is handled automatically.
- Accessibility: The design system aims to meet level AA accessibility standards.
- Native Experience: Features should be built natively within Docker Desktop, avoiding scenarios that force the user to navigate to external web pages or the CLI to perform core functions.
Sources: content/manuals/extensions/extensions-sdk/design/design-guidelines.md:11-17, content/manuals/extensions/extensions-sdk/design/_index.md:11-14
The diagram below illustrates the relationship between the different parts of the design and theming system.
UI Framework and Theming Engine
The officially recommended and supported framework for building extension UIs is React with Material-UI (MUI). This stack is automatically configured by the docker extension init command.
Recommended Framework: React + MUI
Using the recommended stack provides significant advantages:
- Automatic Styling: By using the
@docker/docker-mui-themenpm package, your extension will automatically replicate Docker Desktop's look and feel. - Future Compatibility: Future utilities and components released by Docker will target this specific framework combination.
The following flowchart shows the recommended path for UI development.
Discouraged: Other Frameworks
While it's possible to use other frameworks, it is highly discouraged. Doing so introduces several challenges:
- Manual Theming: You must manually replicate the look and feel of Docker Desktop, which is a significant effort.
- High Maintenance: Whenever the Docker Desktop theme changes, you will need to update your extension to match, increasing the maintenance burden.
- Review Process: Extensions that do not closely match the Docker theme may be asked to make changes during the marketplace review process.
Sources: content/manuals/extensions/extensions-sdk/design/_index.md:27-35
Theming Best Practices
To ensure future compatibility and a robust UI, it is critical to assume that the theme can and will change at any time. Hardcoding styles will lead to a brittle UI that may break with future Docker Desktop updates.
Assume a Dynamic Theme
Any part of the theme might change without warning, including fonts, border styles, colors, and spacing.
The following table summarizes the best practices for building a theme-resilient UI.
| Do This (Good Practice) | Don't Do This (Bad Practice) |
|---|---|
| Override default styling as little as possible. | Fine-tune UI with precise colors, offsets, and font sizes. |
Use semantic typography components like Typography and Link with variant props. | Use raw HTML elements like <p>, <h1> directly for typography. |
Use canned sizes for components (e.g., size="small" on buttons). | Specify sizes in pixels (e.g., fontSize: '14px'). |
Prefer semantic colors from the theme (e.g., error, primary). | Use explicit color codes (e.g., #FF0000). |
Use layout components like Stack or Grid for spacing. | Write custom CSS for margins and padding between elements. |
| Only use colors from the official palette. | Use custom colors that are not part of the design system. |
Sources: content/manuals/extensions/extensions-sdk/design/mui-best-practices.md:12-30, content/manuals/extensions/extensions-sdk/design/_index.md:41-43
Custom Component Strategy
If you need a UI component that doesn't exist in the design system, the recommended process is to first contact the Docker team. If a custom solution is still required, it should be defined in a reusable way to make future updates easier.
This flowchart outlines the process for handling custom UI needs.
Content Components and Formatting
The principles of theming and consistency extend to the markdown content itself. Docker's documentation uses a set of standardized components and formatting rules to present information clearly and consistently.
Callouts
Callouts are used to emphasize selected information. They use a GitHub-style blockquote syntax and are available in several types.
| Callout Type | Syntax | Use Case |
|---|---|---|
| Note | > [!NOTE] | For information that may not apply to all readers or is tangential to a topic. |
| Tip | > [!TIP] | To provide helpful advice or shortcuts. |
| Important | > [!IMPORTANT] | To signal actions that may cause lower-magnitude issues. |
| Warning | > [!WARNING] | To signal actions that may cause damage to hardware or software, or loss of data. |
| Caution | > [!CAUTION] | To warn about potentially dangerous or irreversible actions. |
It is considered good practice to avoid placing too many callouts on one page to prevent a cluttered appearance and diminish their impact.
Sources: content/contribute/style/formatting.md:82-100, content/contribute/components/call-outs.md:1-48
Badges
Badges are used to indicate the status of content or features within the product lifecycle.
| Badge Color | Usage |
|---|---|
violet | Highlight new early access or experimental content. |
blue | Highlight beta content. |
green | Highlight new GA content or non-product content like guides. |
gray | Highlight deprecated content. |
Badges can be used inline or in the page's frontmatter to appear in the sidebar.
Sources: content/contribute/components/badges.md:16-24
UI Element Formatting
When referring to UI elements like buttons, fields, or menus in documentation, specific formatting rules apply to ensure clarity and consistency.
- Formatting: Use bold formatting for the visible names of UI elements (e.g., "Select the Create button.").
- Capitalization: Follow the capitalization as it appears in the UI. If the UI is inconsistent, use sentence case.
- Terminology: Use standard terms consistently (e.g.,
button,field,tab,dialog). - Actions: Prefer
selectoverclickas it is more device-agnostic.
Sources: content/contribute/ui.md:9-19, 41-54
Summary
The theming and CSS structure within the Docker documentation and extension ecosystem is designed to create a unified, accessible, and professional user experience. By adhering to the recommended React+MUI framework and the @docker/docker-mui-theme, developers can ensure their extensions are visually aligned with Docker Desktop. Following best practices, such as using semantic theme properties and avoiding hardcoded styles, is essential for creating robust UIs that are resilient to future updates. This structured approach to styling not only benefits end-users but also streamlines the development and review process for extension authors.
Sources: content/manuals/extensions/extensions-sdk/design/_index.md, content/manuals/extensions/extensions-sdk/design/mui-best-practices.md