You can change the application-wide appearance of an MDriven Turnkey app by setting theme variables in CSS, deploying a compiled theme file, or storing generated CSS as model data; this page is for developers who need to apply and maintain that shared visual theme.

Choose a theming approach

A theme controls the shared appearance of the Turnkey application: colors, typography, component sizes, navigation, actions, and data tables. Use it for changes that should be consistent throughout the application.

This is different from styling an individual UI element according to business data. For example, setting the application primary color to blue is theming; showing a specific status label in green when its value is positive is data-driven styling. See HowTos:Styling and Theming Your Application for that distinction and Documentation:Turnkey Styling for component style references and modifier classes.

Approach	Use it when	Where the CSS is kept	Key consideration
CSS custom properties in tkusercss.css	You want to adjust the supplied Turnkey theme variables without compiling SCSS.	A file in your model assets under Content.	This is the recommended file-based starting point for colors, sizing, and other exposed variables.
Compiled theme-user.css	You need a broader SCSS-based theme customization.	A generated CSS file under Content or Content/scss.	Turnkey uses this file instead of its default Content/theme-default.css when it is present.
Theme as data	Your application must select or regenerate themes while it runs.	Model data.	CSS in tkusercss.css, when set, overrides the corresponding CSS produced from theme data.

For a visual overview, watch the theming overview.

Set theme variables with tkusercss.css

CSS custom properties, also called CSS variables, let you supply values that the Turnkey StyleSystem uses across the application. This approach changes the shared theme without compiling Sass or SCSS.

Create and deploy the file

1. Create the assets folder next to your model file. Its name must be the model filename with the extension replaced by _AssetsTK. For example, for products.azurewebsites.net__MDrivenServerA0.modlr, use products.azurewebsites.net__MDrivenServerA0_AssetsTK.
2. In that folder, create Content/tkusercss.css.
3. Add a :root rule and set the variables you want to override.
4. Upload the model from MDriven Designer. The assets folder is included with the uploaded model and replicated into the Turnkey site. See Documentation:Theme and style for the asset-copy behavior and troubleshooting.
5. Reload the application and verify the changed elements.

For example, this file changes the base font size, navigation bar, primary color, and the colors used for Save actions:

:root {
  --base-font-size: 16px;
  --navbar-bg-color: 24, 56, 96;
  --navbar-brand-color: 255, 255, 255;
  --primary-color: 38, 112, 196;
  --primary-color-dark: 24, 84, 150;
  --text-on-primary: 255, 255, 255;
  --save-action-bg-color: 38, 112, 196;
  --save-action-bg-color-dark: 24, 84, 150;
  --save-action-text-color: 255, 255, 255;
}

Variable format

Put color values in comma-separated RGB format, without rgb(), #, or a color name. For example, use --primary-color: 245, 156, 26;.

Use pixel values for properties identified as pixels, such as --base-font-size: 16px;. Keep each declaration inside the :root { ... } block.

Available variables

Area	CSS custom properties
Base and navigation	--base-font-size --base-bg-color --base-border-radius --navbar-height --navbar-bg-color --navbar-brand-color --navbar-link-color --sidebar-bg-color
Primary color	--primary-color --primary-color-dark --text-on-primary
Context colors	--danger-color --danger-color-dark --text-on-danger --warning-color --warning-color-dark --text-on-warning --success-color --success-color-dark --text-on-success
Action buttons	--save-action-bg-color --save-action-bg-color-dark --save-action-text-color --cancel-action-bg-color --cancel-action-bg-color-dark --cancel-action-text-color --redo-action-bg-color --redo-action-bg-color-dark --redo-action-text-color --undo-action-bg-color --undo-action-bg-color-dark --undo-action-text-color
Data tables	--data-table-header-bg-color --data-table-header-text-color --data-table-header-height --data-table-body-bg-color --data-table-body-text-color --data-table-row-height

Use theme as data for runtime selection

Use Theme as data when the CSS must be held in the application and changed in response to application data. This enables multiple CSS rule sets to be selected at runtime rather than deploying a different CSS file.

Turnkey looks for SysSingleton.oclsingleton.PickedThemeData. The selected object must provide Name:string and DerivedCSS:string. For example, an application can keep one theme object for a standard visual identity and another for an alternative visual identity, then set the selected theme object through PickedThemeData.

Use the StylesInModel dialog to identify theme variable names that affect Turnkey. When testing changes, you may need to update web.config, restart the Turnkey site, and reload the browser page. See Documentation:Theme as data for the model pattern and runtime CSS generation details.

Precedence: a corresponding rule in tkusercss.css overrides the value supplied by theme data.

Legacy workflow: compile an SCSS theme

SCSS (Sass) is a text format that compiles to CSS. Use this workflow when CSS custom properties do not cover the required theme change and you need to work from the Turnkey SCSS source. It remains valid, but CSS variables and Theme as data are usually better starting points for new changes.

Work locally

1. Start a local prototype run with the LocalTurnkeyPrototyper option. You can choose any free port.
2. Locate the supplied SCSS files in application-root/Content/scss.
3. Open the SCSS files in an editor with SCSS support, such as Visual Studio Code.
4. Configure a Sass compiler to watch your SCSS files. The previous workflow used the Live Sass Compiler extension for Visual Studio Code.
5. Edit the SCSS source and save it. The compiler produces application-root/Content/scss/theme-user.css.
6. Refresh the local prototype in the browser to inspect the result.

When theme-user.css is present, Turnkey uses it instead of application-root/Content/theme-default.css. Typical SCSS theme changes include primary and contextual colors, navigation colors, action and button colors, font sizes, and the size of buttons and input components.

Keep the edited SCSS source outside the Turnkey core installation. Updating the Turnkey core can replace the supplied SCSS files. Keep the SCSS source even after generating CSS: the generated CSS does not provide a way to reconstruct the original SCSS structure.

Deploy the compiled CSS

1. Generate and test theme-user.css locally.
2. Copy the generated file into the model assets folder as either Content/scss/theme-user.css or Content/theme-user.css.
3. Upload the model from MDriven Designer.
4. Reload the deployed Turnkey application and verify the theme.

The asset folder contents are copied into the site during model upload. For file replication details, permissions problems, and the expansion log, see Documentation:Theme and style.

Remove a deployed file-based theme

To return to the default compiled Turnkey theme, remove the deployed theme-user.css from the applicable Content/scss or Content location.

When managing files through the assets replication mechanism, use the removal methods described in Documentation:Theme and style. A file with a .DELETE extension removes its matching deployed file. A root-level CleanAll.txt in the assets folder resets known asset locations to their default state; use it when you intentionally need to clear a larger set of deployed assets.

Precompiled theme files

The following precompiled theme downloads contain a theme-user.css file. Extract the archive, place that file in the Content folder in your assets folder, and upload the model.

• File:MDriven Dark theme.zip
• File:Vivid blue theme.zip
• File:Lime green theme.zip
• File:Dark blue theme.zip
• File:Dark red theme.zip
• File:Compact theme.zip — reduces component size so more information fits on a page.

See also

• HowTos:Styling and Theming Your Application
• Documentation:Turnkey Styling
• Documentation:Theme as data
• Documentation:Theme and style
• Documentation:UI&Styling

Color review for Turnkey themes

When changing theme colors, review related background and text variables together. The available CSS custom properties include explicit text-on-color variables for primary, danger, warning, and success colors, as well as text-color variables for actions and data tables.

Create or update tkusercss.css in the model directory's Content folder. Color properties use RGB format, for example 245, 156, 26. Upload the model with MDriven Designer after updating the file.

Review related variables together

The following documented variables have corresponding background and text-color names. When changing one of these backgrounds, review the corresponding text-color value as part of the same theme change.

Color area	Background variable	Related text variable
Primary	--primary-color	--text-on-primary
Danger	--danger-color	--text-on-danger
Warning	--warning-color	--text-on-warning
Success	--success-color	--text-on-success
Save action	--save-action-bg-color	--save-action-text-color
Cancel action	--cancel-action-bg-color	--cancel-action-text-color
Redo action	--redo-action-bg-color	--redo-action-text-color
Undo action	--undo-action-bg-color	--undo-action-text-color
Data-table header	--data-table-header-bg-color	--data-table-header-text-color
Data-table body	--data-table-body-bg-color	--data-table-body-text-color

Also review the navbar color variables together: --navbar-bg-color, --navbar-brand-color, and --navbar-link-color.

Suggested review workflow

1. Create or update Content/tkusercss.css in the model directory.
2. For each background color you change, review its related text-color variable where one is listed above.
3. Review the updated theme in the application, including areas that use navigation, actions, and data tables.
4. Upload the model with MDriven Designer.

For example, this fragment keeps the primary and save-action color values together in the same :root declaration:

:root {
  --primary-color: 245, 156, 26;
  --text-on-primary: 0, 0, 0;

  --save-action-bg-color: 245, 156, 26;
  --save-action-bg-color-dark: 245, 156, 26;
  --save-action-text-color: 0, 0, 0;
}

SCSS-based themes

For a full SCSS theme, the Sass compiler produces theme-user.css. The Turnkey application uses application-root/Content/scss/theme-user.css instead of the default application-root/Content/theme-default.css. To deploy the resulting CSS, copy it into the model's AssetsTK folder with the corresponding Content/scss/theme-user.css or Content/theme-user.css path, then upload the model.

Review the resulting theme after compiling and refreshing the local application.

Choose a theming workflow

MDriven Turnkey supports more than one way to change an application's appearance. Choose the approach that matches the scope of the change.

Need	Use	Result
Quickly change supported shared appearance settings without compiling SCSS	Content/tkusercss.css with CSS custom properties	Turnkey uses the custom-property values you define, such as colors, base font size, border radius, and navigation-bar settings.
Change the broader theme source or styles beyond the available custom properties	Edit SCSS locally and compile theme-user.css	When present, application-root/Content/scss/theme-user.css is used instead of application-root/Content/theme-default.css.

Use CSS custom properties for quick changes

Create tkusercss.css in your model directory's Content folder. Define values in a :root block, then upload the model with MDriven Designer.

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

The available properties include settings for the base font size, background color, border radius, navigation bar, sidebar, primary color, and contextual colors such as danger, warning, and success. Refer to the list of changeable properties in this article before adding values.

Use SCSS for broader theme changes

For source-level theme changes, run the application locally with the LocalTurnkeyPrototyper option. The Turnkey SCSS files are located in application-root/Content/scss. Edit them in an SCSS-capable editor and use a Sass compiler to generate theme-user.css.

Refreshing the local application lets you review the compiled theme. Keep a copy of edited SCSS source files: the documentation warns that they can be overwritten when the Turnkey core is updated.

To deploy the compiled result, copy Content/scss/theme-user.css to the model's AssetsTK folder using the documented folder structure, then upload the model. To return to the standard theme, delete the deployed theme-user.css file.

Review variables in Live-View

The Turnkey Live-View provides model access to CSS variables for theming. Use it to inspect and work with the variables available to the application.

See also

• HowTos:Styling and Theming Your Application
• Documentation:TwoTypesOfStyling