Documentation:Design system and theming strategy

Design system and theming strategy

This page was created by Wikiadmin on 2026-07-29. Last edited by Wikiadmin on 2026-07-29.

You can use this guide to plan a consistent MDriven user interface when you build applications with MDriven Turnkey and MDriven Designer.

Design-system strategy

Treat the system gist and the user interface's modernity and fashion as separate concerns. The model describes the system gist, while the user interface and delivery layer handle the current look and feel. This separation lets you evolve colors, typography, spacing, and rendering without redefining the domain model.

A ViewModel folds parts of the model into a declarative user interface. Use ViewModels to decide which information and actions a user sees. Use theming for choices that should be consistent across the application, such as the primary color or base font size.

Choose the right styling approach

There are two different angles to styling: the overall theme and look of the application, and styling that conveys information from data.

Need	Use	Example
Apply one visual language throughout the application	Theme values and CSS variables in the MDriven Turnkey StyleSystem	Set the primary color, navbar color, base font size, or button and input sizes.
Change the appearance of a specific value based on business data	A style referenced by a styling expression on a ViewModel column	Show a label in green when a condition is true and red when it is false.
Change the underlying Turnkey stylesheet	SCSS source files compiled to `theme-user.css`	Change theme source files locally, compile them, and review the result in the local prototype.

For the distinction between these approaches, see Two Types of Styling and Styling and Theming Your Application.

Apply an application-wide theme

Use CSS custom properties when you want to change the overall appearance without compiling the SCSS source. CSS custom properties, also called CSS variables, are values such as colors, sizes, and font settings that the Turnkey application uses throughout its interface.

Create tkusercss.css in the model directory's Content folder.
Add a :root declaration and define the CSS custom properties that you want to change.
Upload the model with MDriven Designer.

For example, this file changes the base font size and primary color values:

:root {
  --base-font-size: 16px;
  --primary-color: rgb(0, 120, 180);
}

Available properties include --base-font-size, --base-bg-color, --navbar-height, --navbar-bg-color, --primary-color, contextual colors, and button and input sizes. Use the documented property names and value formats in MDriven Turnkey theming.

Build a theme from SCSS

Use SCSS when you need to work with the Turnkey theme source. SCSS is a text format that compiles into CSS and supports variables and logic not available in standard CSS.

Open the original SCSS files in application-root/Content/scss in Visual Studio Code.
Refresh the local prototype to review each change.
Keep the edited SCSS source outside the Turnkey core because updating the Turnkey core overwrites the default styles.

The compiler produces application-root/Content/scss/theme-user.css. Turnkey uses that file instead of application-root/Content/theme-default.css. To deploy the result, copy theme-user.css to the model's AssetsTK folder with the matching Content folder structure, then upload the model.

To return to the standard theme, delete theme-user.css from the application or uploaded AssetsTK location.

Convey information with data-driven styles

Use data-driven styling when a visual change communicates the state of a value rather than the application's overall brand. Maintain the styles in the model, then reference the style name in the styling expression on the relevant ViewModel column.

For example, a label can select a green style when ThingsAreSuperGreat is true and a red style when it is false:

self.ThingsAreSuperGreat->casetruefalse(selfVM.Styles.TheGreenStyle,selfVM.Styles.TheRedStyle)

This is not a replacement for the application theme. The theme defines shared visual defaults; the expression selects a style for a specific data situation.

Review theme changes

Keep application-wide decisions together. For example, define the primary color and navbar colors as theme values instead of repeating color declarations for individual views. Keep business-state cues with the ViewModel column and its styling expression; for example, use a green or red label to communicate a condition.

When you change SCSS, test in the local prototype before deploying. Preserve the edited SCSS source because compiled CSS cannot be converted back to the original SCSS source.

Contents