Telerik
/
blazor-docs
зеркало из https://github.com/telerik/blazor-docs.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

docs(common): Update information about custom themes and color variables (#2103) 

* docs(themes): Polish Themes documentation with Color System info

* docs(themes): Color-related updates

* Update knowledge-base/common-theme-customization-options.md
This commit is contained in:
Dimo Dimov 2024-05-14 19:47:36 +03:00 коммит произвёл GitHub
Родитель 40643ba821
Коммит 6aa4c3820f
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: B5690EEEBB952194
7 изменённых файлов: 105 добавлений и 727 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

39
_contentTemplates/common/general-info.md
Просмотреть файл

@ -10,45 +10,6 @@ Make sure that you have a NuGet feed source with the version you want to upgrade
The `Format` is culture-specific and the same format may produce different results depending on the culture. You can find more information and examples in the [Supported Date Formats]({%slug components/dateinput/supported-formats%}) article.
#end
#cdn
You can reference the built-in Telerik assets like the JS Interop file and the theme stylesheets from a cloud CDN instead of a local resource on your server.
* The [Telerik UI for Blazor CDN]({%slug themes-swatch-distribution%}#telerik-blazor-cdn) distributes the most common [swatches]({%slug themes-swatches%}) for each base theme.
* The additional Themes CDN distributes [all available swatches for the built-in themes]({%slug themes-swatches%}#built-in-themes-and-swatches-list).
<div class="skip-repl"></div>
````CSHTML
<!DOCTYPE html>
<html>
<head>
. . .
<!-- Choose only one of the themes -->
<link rel="stylesheet" href="https://blazor.cdn.telerik.com/blazor/{{site.uiForBlazorLatestVersion}}/kendo-theme-default/all.css" />
<!--
<link href="https://blazor.cdn.telerik.com/blazor/{{site.uiForBlazorLatestVersion}}/kendo-theme-bootstrap/all.css" rel="stylesheet" />
<link href="https://blazor.cdn.telerik.com/blazor/{{site.uiForBlazorLatestVersion}}/kendo-theme-material/all.css" rel="stylesheet" />
-->
<script src="https://blazor.cdn.telerik.com/blazor/{{site.uiForBlazorLatestVersion}}/telerik-blazor.min.js" defer></script>
</head>
. . .
</html>
````
>important Make sure that the version in the URLs matches the version of the Telerik UI for Blazor package.
>tip If you decide to use a CDN over static assets, you may want to implement a [fallback]({%slug common-kb-cdn-fallback%}) if the CDN is unavailable to your users.
#end
#vsx-download
You can get the extension from:

493
_contentTemplates/common/theme-variables.md
Просмотреть файл

@ -1,493 +0,0 @@
#variables-usage
<style>
.theme-variables th,
.theme-variables td {
vertical-align: top;
}
.color-preview {
border-radius: 50%;
width: 1em;
height: 1em;
vertical-align: middle;
display: inline-block;
border: 1px solid rgba(0, 0, 0, .08);
}
</style>
The following example demonstrates how to use common variables.
<table class="theme-variables">
<colgroup>
<col style="white-space:nowrap; width: 200px" />
<col style="width: 250px" />
<col />
</colgroup>
<tr>
<th>Name</th>
<th>Default value</th>
<th>Description</th>
</tr>
<tr>
<td>$font-size</td>
<td>
14px
</td>
<td>Base font size across all components.
</td>
</tr>
<tr>
<td>$font-family</td>
<td>
inherit
</td>
<td>Font family across all components.
</td>
</tr>
<tr>
<td>$font-family-monospace</td>
<td>
Consolas, "Ubuntu Mono", "Lucida Console", "Courier New", monospace
</td>
<td>Font family for monospaced text. Used for styling the code.
</td>
</tr>
<tr>
<td>$line-height</td>
<td>
(20 / 14)
</td>
<td>Line height used along with $font-size.
</td>
</tr>
<tr>
<td>$border-radius</td>
<td>
2px
</td>
<td>Border radius for all components.
</td>
</tr>
<tr>
<td>$accent</td>
<td>
<span class="color-preview" style="background-color: #ff6358"></span>
#ff6358
</td>
<td>The color that focuses the user attention.<br />
Used for primary buttons and for elements of primary importance across the theme.
</td>
</tr>
<tr>
<td>$accent-contrast</td>
<td>
<span class="color-preview" style="background-color: #ffffff"></span>
#ffffff
</td>
<td>The color used along with the accent color denoted by $accent.<br />
Used to provide contrast between the background and foreground colors.
</td>
</tr>
<tr>
<td>$base-text</td>
<td>
<span class="color-preview" style="background-color: #656565"></span>
#656565
</td>
<td>The text color of the components' chrome area.
</td>
</tr>
<tr>
<td>$base-bg</td>
<td>
<span class="color-preview" style="background-color: #f6f6f6"></span>
#f6f6f6
</td>
<td>The background of the components' chrome area.
</td>
</tr>
<tr>
<td>$base-border</td>
<td>
rgba( black, .08 )
</td>
<td>The border color of the components' chrome area.
</td>
</tr>
<tr>
<td>$base-gradient</td>
<td>
$base-bg, darken( $base-bg, 2% )
</td>
<td>The gradient background of the components' chrome area.
</td>
</tr>
<tr>
<td>$hovered-text</td>
<td>
<span class="color-preview" style="background-color: #656565"></span>
#656565
</td>
<td>The text color of hovered items.
</td>
</tr>
<tr>
<td>$hovered-bg</td>
<td>
<span class="color-preview" style="background-color: #ededed"></span>
#ededed
</td>
<td>The background of hovered items.
</td>
</tr>
<tr>
<td>$hovered-border</td>
<td>
rgba( black, .15 )
</td>
<td>The border color of hovered items.
</td>
</tr>
<tr>
<td>$hovered-gradient</td>
<td>
$hovered-bg, darken( $hovered-bg, 2% )
</td>
<td>The gradient background of hovered items.
</td>
</tr>
<tr>
<td>$selected-text</td>
<td>
$accent-contrast
</td>
<td>The text color of selected items.
</td>
</tr>
<tr>
<td>$selected-bg</td>
<td>
$accent
</td>
<td>The background of selected items.
</td>
</tr>
<tr>
<td>$selected-border</td>
<td>
rgba( black, .1 )
</td>
<td>The border color of selected items.
</td>
</tr>
<tr>
<td>$selected-gradient</td>
<td>
none
</td>
<td>The gradient background of selected items.
</td>
</tr>
<tr>
<td>$error</td>
<td>
<span class="color-preview" style="background-color: #f5503e"></span>
#f5503e
</td>
<td>The color for error messages and states.
</td>
</tr>
<tr>
<td>$warning</td>
<td>
<span class="color-preview" style="background-color: #fdce3e"></span>
#fdce3e
</td>
<td>The color for warning messages and states.
</td>
</tr>
<tr>
<td>$success</td>
<td>
<span class="color-preview" style="background-color: #5ec232"></span>
#5ec232
</td>
<td>The color for success messages and states.
</td>
</tr>
<tr>
<td>$info</td>
<td>
<span class="color-preview" style="background-color: #3e80ed"></span>
#3e80ed
</td>
<td>The color for informational messages and states.
</td>
</tr>
</table>
The following example demonstrates how to configure the Buttons.
<table class="theme-variables">
<colgroup>
<col style="white-space:nowrap; width: 200px" />
<col style="width: 250px" />
<col />
</colgroup>
<tr>
<th>Name</th>
<th>Default value</th>
<th>Description</th>
</tr>
<tr>
<td>$button-text</td>
<td>
$base-text
</td>
<td>The text color of the buttons.
</td>
</tr>
<tr>
<td>$button-bg</td>
<td>
$base-bg
</td>
<td>The background of the buttons.
</td>
</tr>
<tr>
<td>$button-border</td>
<td>
$base-border
</td>
<td>The border color of the buttons.
</td>
</tr>
<tr>
<td>$button-gradient</td>
<td>
$base-gradient
</td>
<td>The background gradient of the buttons.
</td>
</tr>
<tr>
<td>$button-hovered-text</td>
<td>
$hovered-text
</td>
<td>The text color of hovered buttons.
</td>
</tr>
<tr>
<td>$button-hovered-bg</td>
<td>
$hovered-bg
</td>
<td>The background of hovered buttons.
</td>
</tr>
<tr>
<td>$button-hovered-border</td>
<td>
$hovered-border
</td>
<td>The border color of hovered buttons.
</td>
</tr>
<tr>
<td>$button-hovered-gradient</td>
<td>
$hovered-gradient
</td>
<td>The background gradient of hovered buttons.
</td>
</tr>
<tr>
<td>$button-pressed-text</td>
<td>
$selected-text
</td>
<td>The text color of pressed buttons.
</td>
</tr>
<tr>
<td>$button-pressed-bg</td>
<td>
$selected-bg
</td>
<td>The background color of pressed buttons.
</td>
</tr>
<tr>
<td>$button-pressed-border</td>
<td>
$selected-border
</td>
<td>The border color of pressed buttons.
</td>
</tr>
<tr>
<td>$button-pressed-gradient</td>
<td>
none
</td>
<td>The background gradient of pressed buttons.
</td>
</tr>
<tr>
<td>$button-focused-shadow</td>
<td>
0 3px 4px 0 rgba(0, 0, 0, .06)
</td>
<td>The shadow of focused buttons.
</td>
</tr>
</table>
The following example demonstrates how to configure the Charts.
<table class="theme-variables">
<colgroup>
<col style="white-space:nowrap; width: 200px" />
<col style="width: 250px" />
<col />
</colgroup>
<tr>
<th>Name</th>
<th>Default value</th>
<th>Description</th>
</tr>
<tr>
<td>$series-a</td>
<td>
<span class="color-preview" style="background-color: #ff6358"></span>
#ff6358
</td>
<td>The color of the first series.
</td>
</tr>
<tr>
<td>$series-b</td>
<td>
<span class="color-preview" style="background-color: #ffd246"></span>
#ffd246
</td>
<td>The color of the second series.
</td>
</tr>
<tr>
<td>$series-c</td>
<td>
<span class="color-preview" style="background-color: #78d237"></span>
#78d237
</td>
<td>The color of the third series.
</td>
</tr>
<tr>
<td>$series-d</td>
<td>
<span class="color-preview" style="background-color: #28b4c8"></span>
#28b4c8
</td>
<td>The color of the fourth series.
</td>
</tr>
<tr>
<td>$series-e</td>
<td>
<span class="color-preview" style="background-color: #2d73f5"></span>
#2d73f5
</td>
<td>The color of the fifth series.
</td>
</tr>
<tr>
<td>$series-f</td>
<td>
<span class="color-preview" style="background-color: #aa46be"></span>
#aa46be
</td>
<td>The color of the sixth series.
</td>
</tr>
<tr>
<td>$chart-major-lines</td>
<td>
rgba(0, 0, 0, .08)
</td>
<td>The color of the Chart grid lines (major).
</td>
</tr>
<tr>
<td>$chart-minor-lines</td>
<td>
rgba(0, 0, 0, .04)
</td>
<td>The color of the Chart grid lines (minor).
</td>
</tr>
</table>
The following example demonstrates how to configure the Toolbar.
<table class="theme-variables">
<colgroup>
<col style="white-space:nowrap; width: 200px" />
<col style="width: 250px" />
<col />
</colgroup>
<tr>
<th>Name</th>
<th>Default value</th>
<th>Description</th>
</tr>
<tr>
<td>$toolbar-padding-x</td>
<td>
$padding-x
</td>
<td>The horizontal padding of the container.
</td>
</tr>
<tr>
<td>$toolbar-padding-y</td>
<td>
$padding-x
</td>
<td>The vertical padding of the container.
</td>
</tr>
</table>
#end

9
knowledge-base/common-theme-customization-options.md
Просмотреть файл

@ -36,12 +36,17 @@ Is there a simple and streamlined way to customize all component styles?
## Solution
Generally, there are **three** ways to customize the appearance of the Telerik Blazor components. Each approach adds an extra step to **every** UI for Blazor version update.
Generally, there are **four** ways to customize the appearance of the Telerik Blazor components. All of them, except the first one, add an extra step to **every** UI for Blazor version update.
1. Use color CSS variables to modify an existing theme.
* This approach is supported for theme versions `8.0.0` and Telerik UI for Blazor versions `6.0.0` and above.
* It is a simple and sustainable way to make minor or major customizations to the **colors** of an existing CSS theme, even at runtime.
* Upgrading the Blazor components does not require any additional steps with regard to the CSS code, unless there are breaking changes in the CSS variable names.
* The apperance of the Telerik components depends on CSS code in two different files. If you prefer to avoid this, then create a custom theme.
1. [Use the ThemeBuilder to create a custom theme]({%slug themes-custom%}#using-themebuilder).
* This option allows [customization of the theme **colors** with the free version, or **full control** with the Pro version](https://docs.telerik.com/themebuilder/introduction#themebuilder-tiers).
* Upgrading the custom theme is straight-forward via [manual](https://docs.telerik.com/themebuilder/web-app/migrating-projects) or [automatic](https://docs.telerik.com/themebuilder/web-app/automatic-migrations) approach.
2. [Build a custom theme from our SASS source]({%slug themes-custom%}#manual-alternative).
2. [Build a custom theme from the SASS source]({%slug themes-custom%}#building-themes-from-source-code).
* This option provides **full control** over the resulting CSS code.
* Upgrading requires you to pull the changes from the [**`kendo-themes`** repo](https://github.com/telerik/kendo-themes) and **rebuild** the custom theme. Ideally, make only [variable and style overrides](https://github.com/telerik/kendo-themes/wiki/Core-Code-Concepts) with minimal edits to our source code itself. However, major customizations may require more changes and maintenance.
3. [Override theme styles with additional CSS code]({%slug themes-override%}).

230
styling-and-themes/custom-theme.md
Просмотреть файл

@ -15,201 +15,117 @@ By customizing themes, you can alter the default appearance of the Telerik compo
This article contains the following sections:
* [Using the ThemeBuilder](#using-themebuilder)
* [Manual Alternative](#manual-alternative)
* [Using the Build Process of the Application](#using-the-build-process-of-the-application)
* [Using the Build Process of the Themes](#using-the-build-process-of-the-themes)
* [Using Variables](#using-variables)
* [Comparing the Blazor CSS Customization Approaches](#comparing-the-blazor-css-customization-approaches)
* [How to Use a Custom Theme I Have](#how-to-use-a-custom-theme-i-have)
* [Contribution](#contribution)
* [Compare the visual customization options for the Telerik Blazor components](#blazor-css-customization-options)
* [Create custom themes with the Progress ThemeBuilder](#using-themebuilder)
* [Customize theme variables](#setting-theme-variables)
* [Build custom themes manually](#building-themes-from-source-code)
* [Load a custom theme in your app](#loading-custom-themes)
* [Contribute](#contribution)
> When you use custom themes for Telerik UI for Blazor components, you must recreate the custom theme every time you update the Telerik components in your application. This ensures compatibility and allows you to get the theme updates and fixes.
## Visual Customization Options
You can customize the appearance of the Telerik Blazor components in several ways. Each has pros and cons, and each is most suitable for specific scenarios and business requirements. The [Blazor Theme Customization Options]({%slug common-kb-theme-customization-options%}) article offers a comparison between these CSS customization alternatives.
>tip When you use custom themes for Telerik UI for Blazor components, you must re-generate the custom theme every time you updates the Telerik components in your project. This allows you to get the theme updates and fixes.
## Using ThemeBuilder
[ThemeBuilder]({%slug themebuilder%}) is a web application that enables you to create new themes and customize existing ones. Every change that you make is visualized almost instantly. Once you are done styling the UI components, you can export a zip file with the styles for your theme and use them in your Blazor app.
## Manual Alternative
Each Kendo UI theme package includes the source files of the respective theme and, thus, provides options for you to modify and rebuild the theme as part of your build process.
For example, you can change the theme colors, remove the CSS of unused components, or use specific theme colors to style your application. The theme source files are located in the scss folder of the theme package.
For the full list of variables that can be modified in a theme, refer to the [Using Variables](#using-variables) section.
To build a custom theme by using the theme variables, apply either of the following approaches:
* [(Recommended) Use the build process of your application](#using-the-build-process-of-the-application)&mdash;This approach simplifies the upgrades to new theme package versions.
* [Use the build process of the themes](#using-the-build-process-of-the-themes)&mdash;This approach requires you to build the theme each time the theme packages are updated.
### Using the Build Process of the Application
When you want to built the Telerik themes yourself (for example, to combine them with the rest of your styles in to one stylesheet), review the following article first, before continuing with the steps below: [https://github.com/telerik/kendo-themes/wiki/Compiling-themes](https://github.com/telerik/kendo-themes/wiki/Compiling-themes).
To customize a Sass-based theme, create a `.scss` file and consume the theme package in the following way:
1. Obtain the theme source through the NPM package.
npm install @progress/kendo-theme-default
1. Create a `.scss` file that will consume the theme. For the purposes of the example, this is `styles.scss`.
1. To build the theme files, import them into the `styles.scss` file.
@import "node_modules/@progress/kendo-theme-default/dist/all.scss";
The `dist/all` file adds the styles for all components that are available in the theme. To trim down the size of the generated CSS, import only the source for the components that you use in your application. Each of them could be found in `scss/` folder.
// Import only the Grid and TreeView styles using Node Sass
@import "~@progress/kendo-theme-default/scss/grid/_index.scss";
@import "~@progress/kendo-theme-default/scss/treeview/_index.scss";
// or using Dart Sass
@import "~@progress/kendo-theme-default/scss/grid/";
@import "~@progress/kendo-theme-default/scss/treeview/";
1. To customize the variables that are used in the theme, change the theme before you import the theme files.
$kendo-color-primary: #E82C0C; // brand color
@import "~@progress/kendo-theme-default/dist/all.scss";
1. Build the `styles.scss` file through a Sass compiler.
To use Node Sass (which uses [LibSass](https://sass-lang.com/libsass)), install the compiler with `npm install node-sass --save` and then compile the file with the following command
node-sass styles.scss styles.css
To use [Dart Sass](https://sass-lang.com/dart-sass), install the compiler with `npm install node-sass@npm:sass --save` and then compile the file with the following command
sass styles.scss styles.css
[ThemeBuilder]({%slug themebuilder%}) is a web application that enables you to create new custom themes by changing the styles of existing built-in themes. Every change that you make is visualized almost instantly. Once you are done styling the UI components, you can export a ZIP file with the desired styles and [use the custom theme in your Blazor app](#loading-custom-themes).
### Using the Build Process of the Themes
## Setting Theme Variables
While each Sass-based theme has a dedicated NPM package (for example, @progress/kendo-theme-default), the source code for all themes is located in the [kendo-themes](https://github.com/telerik/kendo-themes) repository which contains a build task that compiles the theme sources to CSS. To customize a theme, modify the source code of the theme and use the build task to produce a CSS file for your application. This approach avoids the need for a setting up a build configuration when you compile SCSS, but may be harder to maintain as the process has to be repeated each time we update a theme.
The Telerik themes define a collection of theme variables and values. Then, these variables take part in CSS rules to apply consistent styles to all Telerik Blazor components.
You have two options to do that (described in turn below):
It is possible to customize the appearance of our components by overriding the theme variable values outside the theme CSS file. This spares the need to create and maintain a full custom theme.
* Customizing Themes with Swatches
* Customizing the Source Code
* Creating Custom Components Bundle
Each theme defines the same collection of variables, but with different values:
#### Customizing Themes with Swatches
* [Default theme variables](https://www.telerik.com/design-system/docs/themes/theme-default/theme-variables/)
* [Bootstrap theme variables](https://www.telerik.com/design-system/docs/themes/theme-bootstrap/theme-variables/)
* [Material theme variables](https://www.telerik.com/design-system/docs/themes/theme-material/theme-variables/)
* [Fluent theme variables](https://www.telerik.com/design-system/docs/themes/theme-fluent/theme-variables/)
A swatch is a set of variables which customizes the appearance of the theme.
The example below shows how to customize some of the theme variables.
* Each swatch is placed in a separate file. A theme may contain multiple swatches.
* Swatches are useful for creating multiple, persistent theme variations.
* The `.css` output file can be shared across projects and requires no further processing.
>caption Override theme color variables
To create a swatch:
````CSHTML
@if (RenderCustomVariables)
{
<style>
:root {
--kendo-color-base: #ddf;
--kendo-color-base-hover: #eef;
--kendo-color-base-active: #ccf;
--kendo-color-on-base: #00c;
1. Clone the [kendo-themes](https://github.com/telerik/kendo-themes) GitHub repository.
1. Install the [node-gyp](https://github.com/nodejs/node-gyp#installation) package.
1. Install the dependencies for all themes with `npm install && npx lerna bootstrap`.
1. Switch the working directory to `packages/<THEME_NAME>`.
1. Create a `SWATCH_NAME.scss` swatch file in the `scss/swatches` folder.
1. To build the swatches for the theme by running `npm run sass:swatches` or `npm run dart:swatches`.
1. Include the compiled CSS swatch file in your project. It could be found under `dist/SWATCH_NAME.css`.
--kendo-color-primary: #c00;
--kendo-color-primary-hover: #c66;
--kendo-color-primary-active: #900;
--kendo-color-on-primary: #fee;
For example, in the Material theme create `blue-pink-dark` swatch with the following lines:
--kendo-border-radius-md: 1rem;
}
</style>
}
// Variables.
$primary-palette-name: blue;
$secondary-palette-name: pink;
$theme-type: dark;
<p><label><TelerikCheckBox @bind-Value="@RenderCustomVariables" />
Apply Custom Theme Variables</label></p>
// Import the theme file for the components you use.
@import "../panelbar/_index.scss";
@import "../grid/_index.scss";
<TelerikButton>Base Button</TelerikButton>
// Alternatively, include all components.
@import "../all.scss";
<TelerikButton ThemeColor="@ThemeConstants.Button.ThemeColor.Primary">
Primary Button
</TelerikButton>
@code {
private bool RenderCustomVariables { get; set; }
}
````
For the Default and Bootstrap themes, the swatch should look like:
## Building Themes From Source Code
// Variables.
$kendo-color-primary: blue;
$kendo-color-secondary: pink;
The most complex and flexible way to use Telerik themes is to build them from the SASS source code in your development environment.
// Import the theme file for the components you use.
@import "../panelbar/_index.scss";
@import "../grid/_index.scss";
// Alternatively, include all components.
@import "../all.scss";
#### Customizing the Source Code
To create a custom theme by modifying the themes source code:
1. Clone the [kendo-themes](https://github.com/telerik/kendo-themes) GitHub repository.
1. Install the dependencies for all themes with `npm install && npx lerna bootstrap`.
1. Customize the theme variables in the `packages/THEME_NAME/scss/_variables.scss` files.
1. Build the themes with the `npm run sass` or `npm run dart` command to create the customized version of the themes in the `packages/THEME_NAME/dist/all.css` file.
1. After the build completes, reference the compiled CSS in your application.
#### Creating Custom Components Bundle
You might want to omit the styles for some components in the CSS output. To include only the styles that you need:
1. Clone the [kendo-themes](https://github.com/telerik/kendo-themes) GitHub repository.
1. Install the dependencies for all themes with `npm install && npx lerna bootstrap`.
1. Switch the working directory to `packages/<THEME_NAME>`.
1. Create a `CUSTOM_THEME.scss` file in the `scss` folder. For example, create `custom.scss` file with the following lines:
```scss
// Import the theme file for the components you use.
@import "../panelbar/_index.scss";
@import "../grid/_index.scss";
```
1. To build the file, navigate to the theme folder and run `gulp sass --file "scss/CUSTOM_THEME.scss"`.
1. Include the compiled CSS file in your project. It could be found under `dist/CUSTOM_THEME.css`.
The [Theme Customization page of the Progress Design System documentation](https://www.telerik.com/design-system/docs/themes/customization/) and the [kendo-themes repository wiki](https://github.com/telerik/kendo-themes/wiki/Compiling-themes) provide more information about this process.
### Using Variables
## Loading Custom Themes
The following list describes the theme variables available for adjustment in the Kendo UI Default theme.
Custom themes are used in a [similar way as the built-in themes]({%slug getting-started/what-you-need%}#css-theme). The notable differences are:
@[template](/_contentTemplates/common/theme-variables.md#variables-usage)
* The custom theme must reside in the `wwwroot` folder of the Blazor app or on a custom CDN provider.
* You must recreate custom themes every time when you update the Telerik UI for Blazor version.
## Comparing the Blazor CSS Customization Approaches
You can customize the appearance of the Telerik Blazor components in three ways. Each has pros and cons, and each is most suitable for specific scenarios and business requirements. The [Blazor Theme Customization Options]({%slug common-kb-theme-customization-options%}) article offers a comparison between these CSS customization approaches.
## How to Use a Custom Theme I Have
Make sure that the Blazor app is loading only one Telerik theme at a time. If you are replacing a built-in theme with a custom theme, you must remove the `<link>` element of the built-in theme.
You have your custom theme - either generated through the Telerik ThemeBuilder tool, or one that you built yourself, or something that your organization provides.
To use that, instead of one of the built-in themes, you need to:
>caption Adding a custom Telerik theme
1. Add the customized `.css` file to your application, usually in the `wwwroot` folder. For example, it can be in a folder called `myCustomTelerikThemes` and the file itself could be called `SomeCustomTheme.css`.
<div class="skip-repl"></div>
1. Include the custom stylesheet file in the `head` tag of your index document (by default `wwwroot/index.html` for WebAssembly apps and `~/Pages/_Host.cshtml` for server-side Blazor apps). This could looks something like this:
````HTML
<head>
<!-- custom Telerik stylesheet in wwwroot/telerik/ -->
<link rel="stylesheet" href="telerik/custom-theme.css" />
**Index file**
<head>
<!-- More content can be present here -->
<link rel="stylesheet" href="myCustomTelerikThemes/SomeCustomTheme.css" />
<!-- More content can be present here -->
</head>
<!-- other application stylesheets -->
</head>
````
1. Make sure that this is the only Telerik Theme that is referenced in the application. If you are using a built-in theme, you must remove its `<link>` element.
## Contribution
To contribute to the development of the Kendo UI Default Theme, refer to the [telerik/kendo-themes](https://github.com/telerik/kendo-themes) GitHub repository it is stored in.
To contribute to the development of the Kendo UI Themes, go to the [telerik/kendo-themes](https://github.com/telerik/kendo-themes) GitHub repository.
## See Also
* [Progress ThemeBuilder](https://themebuilderapp.telerik.com)
* [Progress ThemeBuilder Documentation](https://docs.telerik.com/themebuilder)
* [Kendo SASS Themes](https://docs.telerik.com/kendo-ui/styles-and-layout/sass-themes)
* [Progress ThemeBuilder](https://themebuilderapp.telerik.com)
* [Progress ThemeBuilder Documentation](https://docs.telerik.com/themebuilder)
* [Kendo SASS Themes](https://docs.telerik.com/kendo-ui/styles-and-layout/sass-themes)

Двоичные данные
styling-and-themes/images/theme-builder-ui-kit-color-styles.png
Просмотреть файл

Двоичный файл не отображается.
Режим "рядом"

До

Ширина:  |  Высота:  |  Размер: 16 KiB

51
styling-and-themes/overview.md
Просмотреть файл

@ -11,36 +11,27 @@ position: 0
# Built-in Themes
The UI for Blazor suite comes with a set of built-in themes that you can choose from to alter the visual appearance of the Telerik components (you can test them in our [live demos](https://demos.telerik.com/blazor-ui/)):
Telerik UI for Blazor comes with a set of built-in themes that you can choose from to alter the visual appearance of our components. You can compare all themes on the [Telerik UI for Blazor live demos](https://demos.telerik.com/blazor-ui/)).
* **Default** - our own neutral styling that suits most cases. Includes the [Ocean Blue accessibility swatch]({%slug themes-accessibility-swatch%}).
* **Bootstrap** - a theme that matches the Bootstrap styling. Read more in the [Bootstrap Notes](#bootstrap-notes) section.
* **Material** - implements the [Material Design Guidelines](https://material.io/design/). Read more in the [Material Notes](#material-notes) section.
* **Fluent** - based on [Microsoft Fluent UI](https://developer.microsoft.com/en-us/fluentui/).
The available built-in themes are:
* **Default** is our own neutral styling that suits most cases. The theme has a [swatch (color variation)]({%slug themes-swatches%}) called [Ocean Blue]({%slug themes-accessibility-swatch%}), which features enhanced accessibility.
* **Bootstrap** matches the styling of the [Bootstrap CSS framework](https://getbootstrap.com). Read more in the [Bootstrap Notes](#bootstrap-notes) section below.
* **Material** implements the [Material Design Guidelines](https://material.io/design/). Read more in the [Material Notes](#material-notes) section below.
* **Fluent** is based on [Microsoft Fluent UI](https://developer.microsoft.com/en-us/fluentui/).
The UI for Blazor suite has the same HTML rendering and SASS Theme stylesheets like other Kendo UI suites, so previous experience with them can be helpful. The components in **UI for Blazor are native components** and not wrappers over jQuery widgets, however.
Telerik UI for Blazor has the same HTML rendering and SASS theme stylesheets as the Kendo UI widgets, so previous experience with them can be helpful. The components in **UI for Blazor are native components** and not wrappers over jQuery widgets.
To use a theme, you must reference its stylesheet in the `<head>` of your main index file. For a [client-side Blazor app]({%slug getting-started/client-side%}), this is `wwwroot/index.html` and for a [server-side Blazor app]({%slug getting-started/server-side%}), it can be `~/Pages/_Host.cshtml` or `_Layout.cshtml` or `App.razor`, depending on the .NET version.
## Using a Theme
This article contains the following sections:
To register a theme, you must reference its stylesheet in the `<head>` the web page. The exact file that contains the `<head>` tag depends on the .NET version and the Blazor application type. See our [Getting Started guides]({%slug blazor-overview%}#getting-started) for more information.
* [Static Assets](#static-assets)
* [CDN](#cdn)
* [Optional Dependency Management](#optional-dependency-management)
* [Libman](#libman)
* [NPM Packages](#npm-packages)
* [Bootstrap Notes](#bootstrap-notes)
The easiest option is to use a theme as a static asset from the NuGet package. The .NET SDK will copy the CSS file to the output folder during build automatically. Static assets provide the following benefits:
## Static Assets
* The application relies on available local resources and not on third parties and remote URLs.
* The theme URL does not change across component versions, which makes product updates easier.
Static assets are part of the NuGet package and the framework will copy them to the output folder during build automatically. They provide the following benefits:
* The necessary resources for the package are always available to you from the framework.
* The application can rely only on local resources and not on third parties (such as CDN providers).
* You do not have to change their paths after updating the package version (a common requirement when using CDNs).
>caption Reference the Telerik theme from the static assets
>caption Load a Telerik theme as a static asset
<div class="skip-repl"></div>
@ -75,10 +66,7 @@ Static assets are part of the NuGet package and the framework will copy them to
</html>
````
## CDN
@[template](/_contentTemplates/common/general-info.md#cdn)
An alternative option is to load a theme from the [Telerik CDN]({%slug common-features-cdn%}). The URLs for the theme swatches are listed in the [Theme Swatches]({%slug themes-swatches%}) article.
## Optional Dependency Management
@ -124,7 +112,9 @@ The [LibMan client-side dependency manager](https://docs.microsoft.com/en-us/asp
}
>note There have been some reports that the `@latest` version sometimes does not work with a message similar to `The "@progress/kendo-theme-material@latest" library could not be resolved by the "unpkg" provider`. If trying again a bit later does not help, you can replace the `@latest` moniker with the current latest version of the theme that you can find at the [Themes Repo Releases section](https://github.com/telerik/kendo-themes/releases). For example, `^3.0.0` to get the latest version of the major release `3`. If you commit such a version, you may want to check for updates after a while.
> Using the `@latest` theme version requires using the latest Telerik UI for Blazor version as well.
>
> There have been some reports that the `@latest` version sometimes leads to an error similar to `The "@progress/kendo-theme-material@latest" library could not be resolved by the "unpkg" provider`. In such cases, you can replace the `@latest` moniker with a [specific theme version](https://github.com/telerik/kendo-themes/releases). For example, use `^8.0.0` to get the latest version of the major release `8`.
>tip You may want to add a package reference to the `Microsoft.Web.LibraryManager.Build` package so that dependencies are resolved at build-time by LibMan, instead of manually. If a version has already been restored, you may need to invoke a `Rebuild` to update it.
@ -154,7 +144,7 @@ The Kendo UI Sass-based themes are located on the Progress NPM registry:
* **Kendo UI Bootstrap v4 Theme**&mdash;Available as @progress/kendo-theme-bootstrap.
* **Kendo UI Material Theme**&mdash;Available as @progress/kendo-theme-material.
You can read more about using this approach in the [Custom Theme - Manual Process]({%slug themes-custom%}#manual-alternative) article.
You can read more about using this approach at [Building Custom Themes]({%slug themes-custom%}#building-themes-from-source-code).
## Material Notes
@ -205,12 +195,15 @@ If you do not want to use the Bootstrap framework to create your layouts, there
* Many other components help with navigation and layouts, review the [list of available components in our demos](https://demos.telerik.com/blazor-ui).
## Next Steps
* [Choose a theme swatch]({%slug themes-swatches%})
* [Create a custom theme]({%slug themes-custom%})
## See Also
* [Style Form Elements]({%slug themes-form-elements%})
* [Change Theme at Runtime]({%slug change-theme-runtime%})
* [Change the Theme at Runtime]({%slug change-theme-runtime%})
* [Live UI for Blazor Demos](https://demos.telerik.com/blazor-ui/)

10
styling-and-themes/themebuilder.md
Просмотреть файл

@ -10,9 +10,9 @@ position: 3
# ThemeBuilder Overview
[ThemeBuilder](https://www.telerik.com/themebuilder) is a web application that enables you to create your custom styles and apply them to the UI components in your Blazor apps.
The [ThemeBuilder](https://www.telerik.com/themebuilder) is a web application that enables you to create your custom styles and apply them to the Telerik UI components in your Blazor apps.
With the [ThemeBuilder app](https://themebuilderapp.telerik.com), you can create new themes, customize existing ones, and organize them in projects. You are in full control of the appearance of every Telerik UI for Blazor component while, at the same time, you can apply large-scale updates in seconds. To speed up the customization of your Blazor app, the ThemeBuilder preview visualizes every style change almost instantly.
With the [ThemeBuilder online tool](https://themebuilderapp.telerik.com), you can create new custom themes, modify existing ones, and organize them in projects. You are in full control of the appearance of every Telerik UI for Blazor component while, at the same time, you can apply large-scale updates in seconds. To speed up the customization of your Blazor app, the ThemeBuilder preview visualizes every style change almost instantly.
Visit the [ThemeBuilder documentation portal](https://docs.telerik.com/themebuilder) to learn how to:
@ -27,12 +27,8 @@ If you work with designers, ThemeBuilder allows you to style the Telerik UI for
To improve the collaboration between designers and developers, Telerik UI for Blazor comes with [four UI Kits for Figma]({% slug ui-kits/themes %}): Material, Bootstrap, Fluent, and Telerik UI Default. Your designers will use them to create the required application design and to apply your brand colors. To implement these design requirements, you need to create a new theme in ThemeBuilder and customize it:
1. Request the designer to send you a link to the UI kit with the customized colors in Figma.
2. Use the link to open the design in Figma.
>If you don't have a Figma account, you can create one for free.
2. Use the link to open the design in Figma. If you don't have a Figma account, you can create one for free.
3. Navigate to the **Components** page and locate the **Color Styles** in the [Inspect Panel](https://help.figma.com/hc/en-us/articles/360055203533-Use-the-Inspect-panel), where you can find the values of all colors used in the design.
![Color Styles in a UI Kit for Figma](./images/theme-builder-ui-kit-color-styles.png)
4. Create a new project in the ThemeBuilder application. To choose the most suitable starting **Theme**, ask your designer which UI Kit was used: **Default**, **Bootstrap**, **Material**, or **Fluent**.
5. Copy the color codes from the **Color Styles** in Figma and paste them into the ThemeBuilder color editor with the same name. For example, copy the value of the `$primary` color in Figma and paste it into the `$kendo-color-primary` color editor in ThemeBuilder.