Theme Authoring Guide
Build a theme from a few base colors, then tune the glass, desktop shell, wallpaper and app icon colors.
Overview
A theme controls how ControlBird looks on desktop and on phones. You can get a complete, consistent result by choosing three colors, then refine the glass surfaces, the desktop top bar, dock and windows, the wallpaper and the app icon colors one setting at a time. Every setting you leave alone keeps its default, so a theme can be as small as one value.
This guide covers creating a theme and the settings on its Materials tab. For the built-in themes, per-user and system-wide themes, and white-label branding, see Themes & White-Labeling.
Create a theme
- Open the Appearance app.
- Select Create theme, or use the duplicate button on an existing theme to start from its values.
- Enter a Theme Name.
- Set colors on the Theme Colors tab and glass, wallpaper and icon settings on the Materials tab.
- Select Create Theme. The theme is saved and applied to your account.
To change a custom theme later, use the edit button on its card and select Save Theme. Built-in themes cannot be edited, but they can be duplicated.
Start with three colors
Three settings on the Theme Colors tab do most of the work:
- Primary Background: the page behind everything.
- Primary Text: the main text color.
- Accent Color: buttons, highlights and the main app icon color.
Pair them for contrast first, then adjust Secondary Background, Deep Accent and the other colors if you want finer control. Several Materials defaults follow these colors, so changing them restyles the glass, the wallpaper and the icons together:
- Glass Tint follows Secondary Background at the Glass Opacity you set.
- Glass Edge Highlight follows Primary Text.
- Glass Shadow follows Primary Background.
- The wallpaper waves follow Accent Color, Deep Accent and the lighter shade of the accent.
- Primary Icon Color follows Accent Color, and Secondary Icon Color follows Deep Accent.
Setting any of these explicitly on the Materials tab overrides the value that would have followed.
Materials settings
Values are typed into the field. Colors accept the color picker or any CSS color, such as #1f2937, rgb(31, 41, 55) or hsl(215, 28%, 17%). Lengths are numbers with an optional unit (px, rem, em, vh or vw). Percentages end in %. A value the editor does not accept is not applied.
Glass Material
Glass is the translucent surface behind windows, menus and the phone header, dock and sheets.
| Setting | What it does | Accepted values |
|---|---|---|
| Glass Blur Strength | How much the content behind a glass surface is blurred. | A length, for example 18px. 0px turns blur off. |
| Glass Opacity | How solid the glass tint is. | A percentage, for example 62%. 100% is fully solid. |
| Glass Tint | The color of the glass. | A color. |
| Glass Edge Highlight | The thin border light around glass surfaces. | A color, usually a translucent one such as rgba(255, 255, 255, 0.2). |
| Glass Shadow | The shadow cast by glass surfaces. | A CSS shadow, for example 0 8px 24px rgba(0, 0, 0, 0.35). |
| Phone Header Background | The header bar in the phone layout. | A color. |
| Phone Dock Background | The dock at the bottom of the phone layout. | A color. |
| Phone Sheet Background | Sheets that slide up over the phone layout. | A color. |
| Phone Card Background | The cards and grouped lists on phone pages, such as Home, Apps and the device list. | A color. |
The phone header follows Secondary Background, and the phone dock and cards follow Primary Background, each kept slightly see-through.
Desktop Shell
The desktop has a top bar with search and your account, a floating dock with your pinned and open apps, a launcher opened from the dock's Apps button or Ctrl+K, and windows whose apps may show a sidebar.
| Setting | What it does | Accepted values |
|---|---|---|
| Top Bar Background | The bar across the top of the desktop. | A color, usually a translucent one so the wallpaper shows through. |
| Dock Background | The floating dock at the bottom of the desktop. | A color. |
| Active Dock Item | The tile behind the app you are working in, and the open launcher. | A color. |
| Launcher Background | The launcher panel and the account menu. | A color. |
| Window Corner Radius | How rounded the desktop windows and the launcher are. | A length, for example 18px. 0px gives square corners. |
| Window Header Background | The header of each window, with its icon, title and location. | A color. |
| Shell Edge Highlight | The light edge around the top bar, dock, launcher, windows and phone cards. | A color, usually a translucent white or, in dark themes, a faint white. |
| Selected Item Text | The text and glyph color of the selected dock item, sidebar section and avatar. | A color. |
| Shell Shadow | The shadow under the dock and phone navigation. | A CSS shadow, for example 0 8px 26px rgba(15, 23, 42, 0.12). |
| App Sidebar Background | The section list on the left of apps such as Device Manager. | A color. |
| Active Sidebar Item | The highlighted section in an app sidebar. | A color. |
The backgrounds follow Secondary Background and Primary Background, and the headers take a hint of the accent, so a theme that sets only its base colors still gets a matching shell. The top bar, dock, launcher and account menu blur what is behind them by the Glass Blur Strength above.
Wallpaper
The same wallpaper sits behind the desktop and the phone layout: a soft background crossed by flowing waves. On the desktop it is shown when the layout's desktop background is set to none or logo; a solid color or image background chosen in the Layout Editor replaces it.
| Setting | What it does | Accepted values |
|---|---|---|
| Wallpaper Base Color | The background behind the waves. | A color. |
| Deep Wave | The strongest color of the main wave. | A color. |
| Bright Wave | The lighter color the main wave fades into. | A color. |
| Mist Wave | The pale wash at the edges of the waves and the far corner of the background. | A color. |
| Wallpaper Image | An image drawn over the waves. | See below. |
The base follows the border color and the waves follow Accent Color, Deep Accent and the lighter shade of the accent. The built-in Dark theme sets its own navy base and deeper waves.
Wallpaper Image accepts one of the following:
none, which shows the waves.- A gradient, for example
linear-gradient(160deg, #0f172a, #1e3a8a)orradial-gradient(circle, #1e3a8a, #0f172a). - An image embedded in the value as a base64 data image.
- An image served from the same site as ControlBird, for example
url(/images/plant.jpg).
External image links are not accepted
A link to an image on another website, such as url(https://example.com/bg.jpg), is rejected. Use a gradient, an embedded data image or an image hosted on your own ControlBird site.
Embedded images are limited in size, so keep them small. For a large photo, host it on your own site and reference it by its same-site address.
App Icon Colors
App icons are line drawings on a pale tile, each app in its own color. They are drawn from nine colors, so one theme recolors every icon consistently. Each app uses one color role:
| Setting | Default follows | Apps that use it |
|---|---|---|
| Primary Icon Color | Accent Color | Device Manager, Model Builder, Schematic 3D Builder |
| Secondary Icon Color | Deep Accent | Config Manager, Schematic Viewer, Schematic 3D Viewer |
| Info Icon Color | The info state color | Database Browser, Layout Editor, Schematic Builder |
| Warning Icon Color | The warning state color | Alarms Config, Faceplate Builder |
| Success Icon Color | The success state color | Certificate Manager, NFC Tags |
| Danger Icon Color | The danger state color | Active Alarms, Calendar, Permissions Manager |
| Purple Icon Color | The purple state color | Extensions, Rule Chain Editor, Appearance |
| Icon Shade Color | The dark gradient color | Logs, Plugin Editor |
| Icon Surface Color | Secondary Background | The tile behind every icon's line drawing |
All nine accept a color.
Turn glass off
For a flat, fully solid look, set Glass Blur Strength to 0px and Glass Opacity to 100%. Surfaces then use their solid tint with no blur or see-through.
Accessibility
- Contrast warning. The Materials tab shows a warning when Primary Text against the resulting glass is under 4.5:1, the common minimum for readable text. The theme can still be saved, so treat the warning as a prompt to adjust Glass Opacity or the text color.
- Reduced transparency. When a device or browser asks for reduced transparency, glass is rendered solid with no blur, whatever the theme sets.
- Reduced motion. When a device asks for reduced motion, the phone layout shortens its animations to near zero.
- Browsers without blur support also get solid surfaces rather than broken ones.
These adjustments apply automatically and need no setting in your theme.
Worked example: Harbor
This theme gives a dark blue control-room look with a cool wallpaper and warmer alert icons. Create a theme named Harbor and set six values:
| Tab | Setting | Value | What it changes |
|---|---|---|---|
| Theme Colors | Primary Background | #0b1220 | A dark navy page, and the glass shadow darkens to match. |
| Theme Colors | Primary Text | #e2e8f0 | Light text, and a soft light edge on glass. |
| Theme Colors | Accent Color | #38bdf8 | Sky blue buttons and highlights, and the Primary Icon Color. |
| Materials | Glass Opacity | 55% | More see-through glass, so the wallpaper shows through the header and dock. |
| Materials | Wallpaper Image | linear-gradient(160deg, #0b1220, #1e3a8a) | A navy-to-blue wallpaper over the waves. |
| Materials | Warning Icon Color | #fb923c | Alarms Config and Faceplate Builder icons turn orange. |
Everything else, including the other icon colors and the rest of the glass settings, keeps its default. If the contrast warning appears after you lower the opacity, raise Glass Opacity or lighten Primary Text.