Two weeks ago we built the Deal Desk app — a three-table model-driven app that gives the sales back office exactly what it needs and nothing more. It worked. And then came the feedback that always comes, usually from someone in marketing: “Great. Why does it look like every other Microsoft product we own?” Fair question. Your users spend all day in this app; the least it can do is wear your colors instead of Redmond’s.
In this post we will apply modern theming to a model-driven app the supported way: a small XML web resource that defines the palette, and the Custom theme definition setting that tells the platform to use it. No CSS hacks, no browser extensions, nothing that breaks on the next wave update. By the end, the Deal Desk app has a black header and our brand red everywhere the platform paints an accent.
Why the Usual Approaches Fall Short
Everyone’s first instinct is the classic theming area — the one buried in the old Settings under Customizations, where you could recolor the navigation bar and stamp a logo. Those legacy themes had two problems: they were organization-wide (every app got the same coat, whether it suited them or not), and they belong to the old UI era. With the refreshed look now the default everywhere, a legacy theme is a bumper sticker on a car you no longer drive.
The other instinct is worse: custom CSS injected through browser tricks or unsupported DOM manipulation. It works beautifully in the demo and dies quietly at the next platform update, and now the app is “broken” in a way no support ticket can fix. Unsupported styling is not a theme, it is a time bomb with a color scheme.
Modern theming replaces both. It is solution-aware, it targets the refreshed UI, it can be scoped per app or per environment, and it consists entirely of supported building blocks: one web resource and one setting.
Prerequisites
- A model-driven app running the refreshed look — which in current environments is simply the look.
- Maker access to the environment and a solution to work in. Mine is the same Blog Demos solution from the Deal Desk build.
- A sandbox. The theme is cosmetic; the habit of testing in a sandbox is not.
Step 1 — Write the Theme XML
The whole theme is one small XML document. Here is the one I used:
<CustomTheme
basePaletteColor="#B01E33"
vibrancy="0"
hueTorsion="0"
>
<AppHeaderColors
background="#1F1F1F"
foreground="#FFFFFF"
backgroundHover="#313131"
foregroundHover="#FFFFFF"
backgroundPressed="#494949"
foregroundPressed="#FFFFFF"
backgroundSelected="#717171"
foregroundSelected="#FFFFFF"
/>
</CustomTheme>Two things do all the work. basePaletteColor is the clever part: you give the platform one brand color and it generates the entire palette from it — hover states, pressed states, selected navigation items, links, focus rings — all mathematically derived shades of your color, with vibrancy and hueTorsion as optional tuning knobs. AppHeaderColors paints the top bar explicitly: I went with a near-black header and white text, which reads as “product,” not “template.” Resist the urge to specify twenty colors; one good base color and a deliberate header beat a hand-tuned rainbow every time.
Step 2 — Upload It as a Web Resource
In the maker portal, open your solution and choose New > More > Web resource. Upload the XML file, set the type to Data (XML), and give it a name you can retype without checking — mine ended up as cr417_dealdesktheme (the publisher prefix is added for you). Save it, and note that full name; it is the one piece of string you will need in a moment.
Step 3 — Add the Custom Theme Definition Setting
The web resource on its own does nothing — the platform needs to be told to use it. That wiring is a setting definition called Custom theme definition, which ships with the platform. In your solution choose Add existing > More > Setting, search for “Custom theme”, select Custom theme definition, and add it. It arrives as just another row in your solution, which is exactly the point: the theme wiring travels with the solution wherever it is deployed.
Step 4 — Point the Setting at Your Web Resource
Select the setting and choose Edit. The pane offers two places to put a value, and the difference matters. A Setting environment value themes every app in the environment — one brand, everywhere. A Setting app value themes only the app you name, and wins over the environment value if both exist. I set an app value for Deal Desk (Demo) only, because my admin apps have no business wearing sales-team red. Either way, the value is simply the web resource’s name — cr417_dealdesktheme — pasted plain, no quotes, no path.
⚠️ Important: the value is the web resource’s unique name exactly as saved, prefix included. Wrap it in quotes, add a space, or typo the prefix and nothing happens — no error, no warning, just an unthemed app and a confused maker. And if you use an app value rather than an environment value, remember the fine print in the pane: the app has to be re-published before the change shows up. “Publish all customizations” covers both the web resource and the app in one click.
Step 5 — Publish and Open the App
Publish all customizations, give it a minute, and open the app. The header is black, the selected navigation item carries the red accent, links and grid highlights follow the palette, and suddenly the Deal Desk app looks like something your company built on purpose.
Limitations and Good Habits
- Pick a mid-tone base color. The palette generator derives light and dark shades from your base; feed it something too pale or too dark and the derived hover and selected states lose contrast. Test with the accessibility checker your organization already claims to use.
- The setting is a preview feature. It has been stable and widely used, but treat it like any preview: test after wave updates, and keep the XML in source control with the rest of the solution.
- It themes the refreshed UI only. Anything still rendering legacy surfaces keeps its old colors. If you spot an unthemed corner, it is usually a legacy component, not a typo in your XML.
- One theme per scope. App value beats environment value; there is no per-role or per-user theming. If two departments demand two brands in one app, you have a governance conversation, not a theming problem.
Closing Thought
Theming an app is painting a room you already renovated. The plumbing was the hard part — the tables, the forms, the security. But nobody walks into a room and compliments the plumbing; they notice the walls. One coat of your own color, applied with supported tools, and the app stops feeling like borrowed office space and starts feeling like yours. Cheap paint, big difference — just use the kind that survives the next renovation.
