docs(common): Styling and Themes revamp (#2205)

* docs(common): Themes documentation revamp * docs(common): Themes revamp next * docs(common): Themes revamp continued * docs(common): Themes revamp continued * docs(common): Themes revamp continued * chore: replace URLs with slugs * docs(common): Themes revamp continued * docs(common): Themes revamp continued * fix slug * add more links to the color system * Update accessibility/accessibility-swatch.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update accessibility/accessibility-swatch.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update common-features/cdn.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update getting-started/vs-integration/upgrade-wizard.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update getting-started/vs-integration/upgrade-wizard.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update knowledge-base/common-telerik-themes-libman.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update knowledge-base/common-telerik-themes-libman.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update knowledge-base/common-telerik-themes-libman.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update styling-and-themes/theme-swatches.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * Update styling-and-themes/theme-swatches.md Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com> * polishing * Update getting-started/vs-code-integration/new-project-wizard.md * fix slug * Improve Change Theme Runtime KB --------- Co-authored-by: Yordan <60105689+yordan-mitev@users.noreply.github.com>
telerik · Aug 1, 2024 · 9667961 · 9667961
1 parent 1449024
commit 9667961
Show file tree

Hide file tree

Showing 60 changed files with 896 additions and 891 deletions.
diff --git a/_config.yml b/_config.yml
@@ -673,7 +673,7 @@ enable_blazorRepl: true
 uiForBlazorLatestVersion: "6.0.2"
 
 ## Compatible theme version for CDN URLs
-themeCdnVersion: "8.0.1"
+themesVersion: "8.1.0"
 
 ## Product
 product: "Telerik UI for Blazor"

diff --git a/_contentTemplates/common/general-info.md b/_contentTemplates/common/general-info.md
@@ -122,6 +122,14 @@ If you set the `ShouldRender` field of the event arguments to `true`, the compon
 | tb-wizard                  | [Wizard]({%slug wizard-overview%})       |
 #end
 
+#change-theme-runtime
+
+### Changing Themes Runtime
+
+The application can remove a loaded stylesheet from the page and register another one. See [how to change the theme or swatch at runtime]({%slug change-theme-runtime%}) with step-by-step instructions and an example.
+
+#end
+
 #status-telerik-com
 ## Telerik NuGet Feed Status
 

diff --git a/_contentTemplates/common/good-styling-practices.md b/_contentTemplates/common/good-styling-practices.md
diff --git a/accessibility/accessibility-swatch.md b/accessibility/accessibility-swatch.md
@@ -1,37 +1,41 @@
 ---
-title: Ocean Blue Accessibility Swatches
-page_title: Ocean Blue Accessibility Swatches
-description: Ocean Blue Accessibility Swatches in the Telerik UI for Blazor suite.
+title: Ocean Blue Accessibility Swatch
+page_title: Default Ocean Blue Accessibility Swatch
+description: Learn about the Default Ocean Blue Accessibility Swatch in the Telerik UI for Blazor suite. This is a theme color variation with enhanced accessibility that complies with accessibility standards.
 slug: themes-accessibility-swatch
-tags: telerik,blazor,accessibility,swatch,theme,ocean,blue,default
+tags: telerik, blazor, accessibility, theme, swatch
 published: True
 position: 7
 ---
 
 # Ocean Blue Accessibility Swatch
 
-The [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/) sections [1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG21/#contrast-minimum) and [1.4.6 Contrast (Enhanced)](https://www.w3.org/TR/WCAG21/#contrast-enhanced) define the required contrast ratio for compliance. The WCAG Level AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. WCAG Level AAA requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text. Telerik UI for Blazor library conforms to WCAG Level AA with the Default Ocean Blue theme swatch (available as of **3.2.0** version).
+The [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/) sections [1.4.3 Contrast (Minimum)](https://www.w3.org/TR/WCAG21/#contrast-minimum) and [1.4.6 Contrast (Enhanced)](https://www.w3.org/TR/WCAG21/#contrast-enhanced) define contrast ratios for accessibility compliance. The *Default Ocean Blue A11y* [theme swatch]({%slug themes-swatches%}) in Telerik UI for Blazor conforms to WCAG Level AA, which requires contrast ratios of at least:
 
-You can test the accessibility swatch in our [live demos](https://demos.telerik.com/blazor-ui/grid/overview) - it is initially selected in the `Change Theme` menu.
+* 4.5:1 for normal text
+* 3:1 for large text
 
-# Default Ocean Blue Accessibility Swatch
 
-The Default Ocean Blue Accessibility Swatch is built on top of [Ocean Blue](#ocean-blue-accessibility-swatch). The difference is that it has contrast focus indicators and is compliant with WCAG requirements.
+## Testing the Accessibility Swatch
 
-You can test the accessibility swatch in our [live demos](https://demos.telerik.com/blazor-ui/grid/overview) - select the `Default Ocean Blue` option in the `Change Theme` dropdown menu.
+To preview and test the Default Ocean Blue A11y swatch, visit the [Telerik UI for Blazor live demos](https://demos.telerik.com/blazor-ui/grid/overview). Enable the swatch from the **Change Theme** dropdown above any of the examples.
 
-> **Limitations:** ColorPalette fails WCAG success criteria 1.4.11. - "Non-text contrast for the focus indicator on its items".
+The Default Ocean Blue A11y swatch is built on top of the Default Ocean Blue swatch. The main difference is that the Ocean Blue A11y swatch has high-contrast focus indicators to comply with WCAG requirements.
 
-Telerik UI for Blazor distributes the Default Ocean Blue theme and the Ocean Blue theme swatches via several resources. Read more in the [Swatch Distribution]({%slug themes-swatch-distribution%}) article.
 
-In addition, both themes are also available in:
+## Using the Accessibility Swatch
+
+You can [obtain and use the Default Ocean Blue A11y swatch]({%slug themes-swatches%}#using-built-in-swatches) starting from the following component and theme versions:
+
+* [Telerik UI for Blazor version 4.0.1](https://www.telerik.com/support/whats-new/blazor-ui/release-history/ui-for-blazor-4-0-1)
+* [Themes version 6.0.3](https://github.com/telerik/kendo-themes/releases/tag/v6.0.3)
+
+Check section [Theme Version Compatibility]({%slug themes-built-in%}#theme-version-compatibility-and-maintenance) for more information about how to align Telerik UI for Blazor versions with theme versions.
+
+> An existing limitation is that the ColorPalette component fails WCAG success criterion 1.4.11. "Non-text contrast for the focus indicator on its items".
 
-* [Themes CDN]({%slug themes-swatches%}#built-in-themes-and-swatches-list)
-* [ThemeBuilder](https://themebuilderapp.telerik.com)&mdash;for testing and [color customization]({%slug themes-custom%})
-* [kendo-themes repository](https://github.com/telerik/kendo-themes)
 
 ## See Also
 
-  * [Accessibility Overview]({%slug accessibility-overview%})
-  * [Accessibility Compliance Components Table]({%slug accessibility-standards%}#accessibility-compliance-components-table)
-  * [Globalization Overview]({%slug globalization-overview%})
+* [Accessibility Overview]({%slug accessibility-overview%})
+* [Component Accessibility Compliance]({%slug accessibility-standards%}#accessibility-compliance-components-table)
diff --git a/common-features/cdn.md b/common-features/cdn.md
@@ -20,7 +20,41 @@ The CDN hosts two kinds of static client assets for the Telerik UI for Blazor co
 
 ## CSS Theme URLs
 
-The CDN hosts [swatches of the popular built-in CSS themes]({%slug themes-swatch-distribution%}). The file URLs look like this:
+The [Telerik CSS themes]({%slug themes-built-in%}) are available on two CDN hosts:
+
+* `unpkg.com` provides [all built-in theme swatches]({%slug themes-swatches%}#swatch-urls). The version number in the theme URL matches the version of the theme itself. Make sure to [use compatible theme and component versions]({%slug themes-swatches%}#theme-version-compatibility-and-maintenance). For example, use theme version `{{site.themesVersion}}` with UI for Blazor version `{{site.uiForBlazorLatestVersion}}`.
+* `blazor.cdn.telerik.com` provides a limited set of popular [theme swatches]({%slug themes-swatches%}). The version number in the theme URL matches the version of the Telerik UI for Blazor components, for example, `{{site.uiForBlazorLatestVersion}}`.
+
+### UNPKG CDN
+
+The CSS file URLs on `unpkg.com` look like this:
+
+<code>unpkg.com/@progress/kendo-theme-**&lt;THEME-NAME&gt;**@**&lt;THEME-VERSION&gt;**/dist/**&lt;SWATCH-NAME&gt;**.css</code>
+
+The separate [font icons]({%slug common-features-icons%}) stylesheet URL looks like this:
+
+<code>unpkg.com/@progress/kendo-font-icons@**&lt;PACKAGE-VERSION&gt;**/dist/index.css</code>
+
+Here are a few examples:
+
+>caption UNPKG CDN URLs for Telerik CSS themes
+
+<div class="skip-repl"></div>
+
+````CHTML
+<!-- Ocean Blue swatch of the Default theme -->
+<link rel="stylesheet" href="https://unpkg.com/@progress/kendo-theme-default@{{site.themesVersion}}/dist/default-ocean-blue.css" />
+
+<!-- Main swatch of the Bootstrap theme -->
+<link rel="stylesheet" href="https://unpkg.com/@progress/kendo-theme-default@{{site.themesVersion}}/dist/bootstrap-main.css" />
+
+<!-- Latest font icon stylesheet -->
+<link rel="stylesheet" href="https://unpkg.com/@progress/kendo-font-icons/dist/index.css" />
+````
+
+### Telerik CDN
+
+The CSS file URLs on `blazor.cdn.telerik.com` look like this:
 
 <code>blazor.cdn.telerik.com/blazor/**&lt;COMPONENT-VERSION&gt;**/kendo-theme-**&lt;THEME-NAME&gt;**/swatches/**&lt;THEME-NAME&gt;**-**&lt;SWATCH-NAME&gt;**.css</code>
 
@@ -60,6 +94,8 @@ The CDN hosts the [JavaScript (JSInterop) file of Telerik UI for Blazor]({%slug
 <script src="https://blazor.cdn.telerik.com/blazor/{{site.uiForBlazorLatestVersion}}/telerik-blazor.min.js"></script>
 ````
 
+> When using the `telerik-blazor.js` file from CDN and with a `defer` attribute, [start the client-side Blazor framework manually]({%slug getting-started/what-you-need%}#javascript-file).
+
 
 ## Pros and Cons of Using CDN
 

diff --git a/common-features/icons.md b/common-features/icons.md
@@ -166,7 +166,7 @@ Our font icons are designed on a 16px grid base. For better display quality, use
 
 ### Render Font Icons with HTML
 
-Telerik UI for Blazor shares the same [themes]({%slug general-information/themes%}) with several other Telerik and Kendo UI web component suites. All these products use the same font icons.
+Telerik UI for Blazor shares the same [themes]({%slug themes-built-in%}) with several other Telerik and Kendo UI web component suites. All these products use the same font icons.
 
 You can use the built-in font icons directly with HTML tags, without the `<TelerikFontIcon>` component. Such direct HTML usage may provide more flexibility, but if you don't really need it, we recommend using `FontIcon` objects and the `<TelerikFontIcon>` component instead.
 

diff --git a/components/button/overview.md b/components/button/overview.md
@@ -14,7 +14,7 @@ This article introduces the <a href="https://www.telerik.com/blazor-ui/buttons"
 
 Buttons convey user actions and can display text, images and HTML.
 
-The Blazor Button provides a variety of styling options through the [built-in themes]({%slug general-information/themes%}) and the [button type]({%slug button-type%}). It supports [font icons and images]({%slug button-icons%}) and fires click [events]({%slug button-events%}).
+The Blazor Button provides a variety of styling options through the [built-in themes]({%slug themes-built-in%}) and the [button type]({%slug button-type%}). It supports [font icons and images]({%slug button-icons%}) and fires click [events]({%slug button-events%}).
 
 ## Creating Blazor Button
 
@@ -57,7 +57,7 @@ To prevent user interaction with a Button, disable it. [Read more about the disa
 
 ## Styling
 
-To customize the style and the appearance of the Blazor Button, you can use the [built-in themes]({%slug general-information/themes%}). Additionally, set the `Class` attribute to implement custom CSS rules or [configure the built-in appearance options]({%slug button-styling%}).
+To customize the style and the appearance of the Blazor Button, you can use the [built-in themes]({%slug themes-built-in%}). Additionally, set the `Class` attribute to implement custom CSS rules or [configure the built-in appearance options]({%slug button-styling%}).
 
 >tip To learn more about the appearance, anatomy, and accessibility of the Button, visit the [Progress Design System documentation](https://www.telerik.com/design-system/docs/components/button/)—an information portal offering rich component usage guidelines, descriptions of the available style variables, and globalization support details.
 

diff --git a/components/button/styling.md b/components/button/styling.md
@@ -13,7 +13,7 @@ position: 10
 There are a few ways to style the Button component:
 
 * Set a [primary button](#primary-button) style.
-* Use another [built-in theme]({%slug general-information/themes%}).
+* Use another [built-in theme]({%slug themes-built-in%}).
 * Use the [Button `Class`](#button-class) attribute.
 
 ## Primary Button

diff --git a/components/buttongroup/overview.md b/components/buttongroup/overview.md
@@ -14,7 +14,7 @@ This article provides information about the <a href="https://www.telerik.com/bla
 
 The ButtonGroup component is a container for [regular and toggle buttons]({%slug buttongroup-buttons%}). Before continuing, make sure you are familiar with the differences between [regular buttons]({%slug components/button/overview%}) and [toggle buttons]({%slug togglebutton-overview%}).
 
-The ButtonGroup component lets you [select one or more toggle buttons]({%slug buttongroup-selection%}), and respond to the [selection and click events]({%slug buttongroup-events%}). The buttons inside fill up the container, match the styling according to the [chosen theme]({%slug general-information/themes%}) and provide the regular button features like images and icons and the other parameters and attributes. 
+The ButtonGroup component lets you [select one or more toggle buttons]({%slug buttongroup-selection%}), and respond to the [selection and click events]({%slug buttongroup-events%}). The buttons inside fill up the container, match the styling according to the [chosen theme]({%slug themes-built-in%}) and provide the regular button features like images and icons and the other parameters and attributes.
 
 ## Creating Blazor ButtonGroup
 

diff --git a/components/fileselect/templates.md b/components/fileselect/templates.md
@@ -10,7 +10,7 @@ position: 30
 
 # FileSelect Templates
 
-The `SelectFilesButtonTemplate` allows you to modify the **Select Files...** button. It lets you change the default text of the button and include custom content like an [icon](/blazor-ui/common-features/icons) or image.
+The `SelectFilesButtonTemplate` allows you to modify the **Select Files...** button. It lets you change the default text of the button and include custom content like an [icon]({%slug common-features-icons%}}) or image.
 
 >caption Using FileSelect SelectFilesButtonTemplate
 

diff --git a/components/loader/appearance.md b/components/loader/appearance.md
@@ -94,7 +94,7 @@ The `ThemeColor` parameter sets the color of the animated loading indicator. You
 * `Light`
 * `Inverse`
 
-These predefined options match the main [Telerik Theme]({%slug general-information/themes%}) and you can see that in action in the [Loader Appearance live demo](https://demos.telerik.com/blazor-ui/loader/appearance).
+These predefined options match the main [Telerik Theme]({%slug themes-built-in%}) and you can see that in action in the [Loader Appearance live demo](https://demos.telerik.com/blazor-ui/loader/appearance).
 
 >caption Built-in Theme Colors
 

diff --git a/components/notification/appearance.md b/components/notification/appearance.md
@@ -139,7 +139,7 @@ The color of the notification popup is easily controlled through the `ThemeColor
 * `Light`
 * `Inverse`
 
-These predefined options match the main [Telerik Theme]({%slug general-information/themes%}) and you can see that in action in the [Notification Appearance](https://demos.telerik.com/blazor-ui/notification/appearance) Live Demo.
+These predefined options match the main [Telerik Theme]({%slug themes-built-in%}) and you can see that in action in the [Notification Appearance](https://demos.telerik.com/blazor-ui/notification/appearance) Live Demo.
 
 There are built-in themes for the most common notifications such as Success, Info, Warning, Error, that also come with predefined icons, so you don't have to set them explicitly.
 

diff --git a/components/radiogroup/overview.md b/components/radiogroup/overview.md
@@ -10,7 +10,7 @@ position: 0
 
 # Blazor RadioGroup Overview
 
-The <a href="https://www.telerik.com/blazor-ui/radiogroup" target="_blank">Blazor RadioGroup component</a> allows the user to select an option from a predefined set of choices in a list of radio buttons. The radio group is styled according to the Telerik [Theme]({%slug general-information/themes%}). You can also choose the [layout order]({%slug radiogroup-layout%}) and [label position]({%slug radiogroup-label-position%}).
+The <a href="https://www.telerik.com/blazor-ui/radiogroup" target="_blank">Blazor RadioGroup component</a> allows the user to select an option from a predefined set of choices in a list of radio buttons. The radio group is styled according to the Telerik [Theme]({%slug themes-built-in%}). You can also choose the [layout order]({%slug radiogroup-layout%}) and [label position]({%slug radiogroup-label-position%}).
 
 ## Creating Blazor RadioGroup
 

diff --git a/components/spreadsheet/overview.md b/components/spreadsheet/overview.md
@@ -77,12 +77,12 @@ The table below lists the Spreadsheet parameters. For a full list of the ListBox
 | `ColumnWidth` | `double` <br /> (`64`) | The initial pixel width of the columns. |
 | `Data` | `byte[]` | The Excel file to display in the Spreadsheet component. |
 | `EnableLoaderContainer` | `bool` <br /> (`true`) | Defines if the component will show a built-in [LoaderContainer]({%slug loadercontainer-overview%}) while loading Excel files. |
-| `Height` | `string` | The `height` style of the `<div class="k-spreadsheet">` element. The [built-in themes]({%slug general-information/themes%}) apply `"600px"` by default. |
+| `Height` | `string` | The `height` style of the `<div class="k-spreadsheet">` element. The [built-in themes]({%slug themes-built-in%}) apply `"600px"` by default. |
 | `RowHeaderWidth` | `double` <br /> (`32`) | The pixel width of the row headers that display the row numbers. The default width fits up to 3 digits comfortably. |
 | `RowHeight` | `double` <br /> (`20`) | The initial pixel height of the rows. |
 | `RowsCount` | `int` <br /> (`200`) | The initial number of rows to render. Users can add and delete rows at runtime. |
 | `Tools` | `SpreadsheetToolSet` <br /> (`SpreadsheetToolSets.All`) | The available tabs and tools that users can use to manipulate the Excel file content. The Spreadsheet renders all its tools by default, so the resulting Spreadsheet UI will change in the future. |
-| `Width` | `string` | The `width` style of the `<div class="k-spreadsheet">` element. The [built-in CSS themes]({%slug general-information/themes%}) apply `"100%"` by default. |
+| `Width` | `string` | The `width` style of the `<div class="k-spreadsheet">` element. The [built-in CSS themes]({%slug themes-built-in%}) apply `"100%"` by default. |
 
 
 ## Spreadsheet Reference and Methods

diff --git a/components/togglebutton/overview.md b/components/togglebutton/overview.md
@@ -12,7 +12,7 @@ position: 0
 
 This article provides information about the <a href="https://www.telerik.com/blazor-ui/togglebutton" target="_blank">Blazor ToggleButton component</a> and its core features.
 
-The ToggleButton component can have a selected state, which is the main difference from the [regular Telerik UI for Blazor Button]({%slug components/button/overview%}). The two-state styling depends on the [chosen theme]({%slug general-information/themes%}). The ToggleButton also provides [events]({%slug togglebutton-events%}), [declarative appearance customization]({%slug togglebutton-appearance%}) and can nest [icons]({%slug togglebutton-icons%}).
+The ToggleButton component can have a selected state, which is the main difference from the [regular Telerik UI for Blazor Button]({%slug components/button/overview%}). The two-state styling depends on the [chosen theme]({%slug themes-built-in%}). The ToggleButton also provides [events]({%slug togglebutton-events%}), [declarative appearance customization]({%slug togglebutton-appearance%}) and can nest [icons]({%slug togglebutton-icons%}).
 
 ## Creating Blazor ToggleButton
 

diff --git a/components/upload/templates.md b/components/upload/templates.md
@@ -10,7 +10,7 @@ position: 30
 
 # Upload Templates
 
-The `SelectFilesButtonTemplate` allows you to modify the **Select Files...** button. It lets you change the default text of the button and include custom content like an [icon](/blazor-ui/common-features/icons) or image.
+The `SelectFilesButtonTemplate` allows you to modify the **Select Files...** button. It lets you change the default text of the button and include custom content like an [icon]({%slug common-features-icons%}) or image.
 
 >caption Using Upload SelectFilesButtonTemplate