Fluent Next Theme: Add New Topics & Old Topic Updates - #9119
Conversation
| The following naming convention applies to CSS variables in Fluent Next themes: | ||
|
|
||
| - `--dxds-*` | ||
| Design System CSS variables that serve as public APIs. Use these variables to customize your DevExtreme-powered application. |
There was a problem hiding this comment.
Actually these variables may be changed as well?
There was a problem hiding this comment.
Ah, I forgot to let you guys know that I am aware that some variables are going to change. I am going to be checking & updating all names here and in the code snippets once the updated naming is finalized.
| @@ -0,0 +1,1541 @@ | |||
| Fluent Next themes ship with 11 predefined accent colors. The blue accent color is available as part of complete theme stylesheets (for instance, `dx.fluent-next.blue.light`). To apply another color, add one of the following `:root` styles to your application before you load a Fluent Next stylesheet: | |||
There was a problem hiding this comment.
The instruction to add the :root block before the Fluent Next stylesheet inverts the cascade. dx.fluent-next.blue.light.css declares the whole accent ramp inside its single :root block, so a user :root block has identical specificity and wins only if it comes after the theme stylesheet. As written, the override silently has no effect. It also contradicts 10 Custom Accent Colors.md, which says "load after the theme stylesheet".
| DevExtreme ships with a set of built-in themes: | ||
|
|
||
| - **Fluent Next** | ||
| [Design System](https://docs.devexpress.com/DesignSystem/405636/foundation)-based themes that use CSS variables to declare color, typography, spacing, border, opacity, and shadow styles. Key features include: |
There was a problem hiding this comment.
| [Design System](https://docs.devexpress.com/DesignSystem/405636/foundation)-based themes that use CSS variables to declare color, typography, spacing, border, opacity, and shadow styles. Key features include: | |
| [Design System](https://docs.devexpress.com/DesignSystem/405636/foundation) - based themes that use CSS variables to declare color, typography, spacing, border, opacity, and shadow styles. Key features include: |
There was a problem hiding this comment.
This is not a typо, this text will be displayed as "Design Sytem-based themes" on the site, worded identically to our Blazor Fluent's description on https://docs.devexpress.com/Blazor/404821/styling-and-themes/styling-and-themes#themes
| - Custom accent color support | ||
| - Light and dark modes | ||
| - Compact mode | ||
| - High contrast mode |
There was a problem hiding this comment.
"High contrast mode" isn't shipping for Fluent Next in 26.2. theme-options.cjs builds only light/dark × default/compact (4 bundles: dx.fluent-next.blue.{light,dark}[.compact].css), the generated token tree contains only semantic/colors/light.scss and dark.scss, and the built CSS has zero forced-colors / prefers-contrast / -ms-high-contrast rules. Please remove the bullet or mark it as planned.
| } | ||
|
|
||
| /* Using custom colors */ | ||
| .dark-colors-custom { |
There was a problem hiding this comment.
.dark-colors-custom sets the surface and the content color to the same #341A51, so text is invisible on its own background. Suggest a light content value, e.g. --dxds-color-content-neutral-default-rest: #F5F0FA;.
|
|
||
| ## Fluent Next Themes | ||
|
|
||
| TBA: Need to discuss images in this section w/ designer |
There was a problem hiding this comment.
TBA: Need to discuss images in this section w/ designer would ship to the public docs. Fluent Next is also the only theme block on this page without images, while it's now listed first.
There was a problem hiding this comment.
Added images from regular fluent for the time being, updating the design & images of this section (I believe it looks a bit strange) will be a task for a later time.
| @@ -1,71 +1,50 @@ | |||
| DevExtreme provides Generic, Generic Compact, Material Design, and Fluent (all trademarks or registered trademarks are property of their respective owners) themes. These themes are available in the following colors: | |||
| DevExtreme ships with the following themes (all trademarks or registered trademarks are property of their respective owners): | |||
There was a problem hiding this comment.
05 Predefined Themes/00 Predefined Themes.md:306 (+ the rename of 00 Styling Methods.md → 02 Styling Methods.md)
The rename leaves 9 topics pointing at the old file path /concepts/60%20Themes%20and%20Styles/00%20Styling%20Methods.md. Verified against the base branch - line 306 of this file plus:
concepts/60 Themes and Styles/10 HTML-Based Components Customization/HTML-Based Components Customization.md
concepts/40 Angular Components/10 Getting Started/03 Add DevExtreme to an Angular CLI Application/03 Configure Stylesheets.md
concepts/40 Angular Components/10 Getting Started/30 Other Approaches/{04 Using Webpack/04,05 Using Ionic/05,06 Using Rollup/04} Import Stylesheets.md
concepts/50 React Components/05 Add DevExtreme to a React Application/40 Import Stylesheets.md
concepts/55 Vue Components/05 Add DevExtreme to a Vue Application/40 Import Stylesheets.md
concepts/Common/Security Considerations/20 HTML Encoding/30 Potentially Vulnerable API/customizeTooltip.md
Please update all of them (or keep the original file name).
There was a problem hiding this comment.
I have renamed Styling Methods to add the new Styling Overview topic at the top of this section within the site's left-hand menu. Renamings like these, where only the number at the front of the file name is changed, do not break links. Our docgen mechanism will update 00 > 02 automatically, we do not add such updates by hand. Link updates are only necessary when text changes.
| @@ -0,0 +1,1541 @@ | |||
| Fluent Next themes ship with 11 predefined accent colors. The blue accent color is available as part of complete theme stylesheets (for instance, `dx.fluent-next.blue.light`). To apply another color, add one of the following `:root` styles to your application before you load a Fluent Next stylesheet: | |||
There was a problem hiding this comment.
Accent colors recolor HTML-based components only. js/__internal/viz/core/themes/fluent-next/index.ts registers the Fluent Next viz themes as plain aliases of fluent.blue.light/fluent.blue.dark, so charts and other SVG-based components stay blue no matter which accent is applied, and they don't read --dxds-* at all. This needs an explicit note in this section - otherwise a user switching to Rose will report it as a bug.
| - Theme customization using public `--dxds-*` CSS variables | ||
|
|
||
| - **Fluent, Material, and Generic** | ||
| Themes that use SCSS to implement styles. For more information, refer to the following help topic: [Predefined Themes](). |
| Design System CSS variables that serve as public APIs. Use these variables to customize your DevExtreme-powered application. | ||
|
|
||
| - `--dx-*` | ||
| Internal CSS variables and classes used by DevExtreme components. May change between versions. |
There was a problem hiding this comment.
This page says --dx-* covers "internal CSS variables and classes" and recommends not using them, but 00 Styling Overview/10 CSS Styles.md recommends the opposite for classes ("You can also use these CSS classes in custom elements…") and links to the public CSS Classes API reference. Please scope the recommendation to variables, so the two topics don't contradict each other.
|
|
||
| <!-- tab: Custom --> | ||
| /* Set --dx-accent-color to a brand color; load after the theme stylesheet. */ | ||
| :root { |
There was a problem hiding this comment.
With the documented knobs the recipe doesn't reproduce the designed palettes. Feeding the recipe its own default #0f6cbd and comparing against _design-system/fluent/accents/blue.scss, the light half is off by ΔE(OKLab) 3–6 - step 10 comes out L 0.950 / C 0.040 vs designed L 0.977 / C 0.007. Those steps back real roles (--dxds-color-surface-primary-deep-* and …-subdued-*, i.e. hover/selected backgrounds), so the difference is visible. --dx-accent-lightness-max: 0.975 + --dx-accent-chroma-min: 0.01 cut the worst light-half deviation from 5.86 to 3.04. Worth stating too that a derived ramp is an approximation of the designed ones.
| You can define a custom accent color as a CSS variable and use this color to calculate `--dxds-primary-*` variables as follows: | ||
|
|
||
| <!-- tab: Custom --> | ||
| /* Set --dx-accent-color to a brand color; load after the theme stylesheet. */ |
There was a problem hiding this comment.
The snippet asks users to define --dx-accent-color and --dx-accent-, but 05 Variable Naming Convention.md calls --dx- internal and advises against using it. These variables also aren't declared by the theme - the user introduces them - so a neutral prefix (--my-accent-color, --my-accent-lightness-max, …) removes the contradiction and avoids a future clash with the component tier.
| --dx-accent-lightness-min: 0.15; | ||
| --dx-accent-chroma-min: 0.04; | ||
|
|
||
| --dxds-primary-10: oklch(from var(--dx-accent-color-source) calc(l + 9 * (var(--dx-accent-lightness-max) - min(l, var(--dx-accent-lightness-max))) / 9) calc(c - 9 * (max(c, var(--dx-accent-chroma-min)) - var(--dx-accent-chroma-min)) / 9) h); |
There was a problem hiding this comment.
oklch(from …) (relative color syntax) has no fallback here. Where it isn't supported, every --dxds-primary-* becomes invalid at computed-value time, so primary surfaces don't degrade gracefully - they lose their color completely. Worth one sentence on the browser requirement (kindly check browsers that devextreme supports, leave the note if need), and optionally wrapping the block in @supports (color: oklch(from red l c h)) so unsupported browsers keep the bundled ramp.
| @@ -0,0 +1,1541 @@ | |||
| Fluent Next themes ship with 11 predefined accent colors. The blue accent color is available as part of complete theme stylesheets (for instance, `dx.fluent-next.blue.light`). To apply another color, add one of the following `:root` styles to your application before you load a Fluent Next stylesheet: | |||
There was a problem hiding this comment.
Two simplifications worth considering: (a) 26.2 already builds ready-to-use accent stylesheets - artifacts/css/accents/.css → dist/css/accents/ (DevExpress/DevExtreme#34767) - so the recipe could be "link this file after the theme" instead of pasting 136 declarations; (b) all 11 palettes are identical except the --dxds-primary-* ramp - I compared all 136 tokens across all 11 files - so the code blocks could be trimmed to the 18 primary steps. As a bonus, the primitives are byte-identical between the light and dark bundles, so one block legitimately covers both modes; that's worth stating explicitly.
| border-color: var(--dxds-color-border-neutral-default-hovered); | ||
| } | ||
|
|
||
| You can also override variables to modify styles for DevExtreme components. This allows you to apply unique styles to different parts of your application. For instance, you can use the following [semantic variable](https://docs.devexpress.com/DesignSystem/405706/colors/color-css-variables) overrides to apply dark mode styles to parts of a light mode application: |
There was a problem hiding this comment.
Container-scoped overrides don't reach overlays: popups, dropdowns, toasts and drag previews render at viewport level, outside .dark-colors-dx, so they inherit the :root values - a SelectBox inside the container gets a light dropdown. Legacy swatches solved this: core/utils/swatch_container.ts finds the nearest dx-swatch-* ancestor and recreates a container with that class inside the viewport. The mechanism keys off the class-name prefix only (no compiled swatch CSS required), so naming the scope class dx-swatch-mydark makes the variable overrides follow overlays. Worth documenting here, since 55 Color Swatches.md now redirects swatch users to this section.
| @@ -0,0 +1,72 @@ | |||
| Fluent Next themes ship with CSS variables defined in the DevExpress Design System. Refer to the following help topics for additional information about key styling principles and a list of available CSS variables: | |||
|
|
|||
| - [Colors](https://docs.devexpress.com/DesignSystem/405706/colors/color-css-variables) | |||
There was a problem hiding this comment.
The "Colors" link goes to the DS semantic variables page, which documents the --dxds-color-* roles but not the --dxds-primary-NN primitives that the Accent Colors topics rely on. Consider linking the DS palette/primitives page as well.
|
|
||
| <!-- tab: CSS --> | ||
| /* Using dxds variables */ | ||
| .dark-colors-dx { |
There was a problem hiding this comment.
[minor] .dark-colors-dx is reused for three different examples, and the yellow accent example isn't about dark colors. Distinct class names would read better.
| --dxds-primary-40: #b4d2f4; | ||
| --dxds-primary-50: #9cc3f0; | ||
| --dxds-primary-60: #82b4ea; | ||
| --dxds-primary-70: #67a2e1; |
There was a problem hiding this comment.
[minor] 9 * (…) / 9 in the step-10 formula is a no-op; --dxds-primary-100: oklch(from … l c h) could simply be the source color. Simplifying makes the pattern easier to read.
| @@ -0,0 +1,3 @@ | |||
| You can apply custom CSS styles to specific classes to customize DevExtreme component appearance. You can also use these CSS classes in custom elements to ensure a consistent look and feel across your app. | |||
|
|
|||
| For a list of common DevExtreme classes, refer to the following help topic: [CSS Classes](/Documentation/ApiReference/UI_Components/CSS_Classes/). No newline at end of file | |||
There was a problem hiding this comment.
Missing trailing newline in 00 Styling Overview/10 CSS Styles.md, 07 Fluent Next Theme Customization/00 Fluent Next Theme Customization.md, 05 CSS Variables/05 Variable Naming Convention.md, 10 Accent Colors/00 Accent Colors.md.
| --dxds-neutral-280: #0a0a0a; | ||
| } | ||
|
|
||
| <!-- tab: Cool Blue --> |
There was a problem hiding this comment.
[suggestion]
The product already ships ready-to-use accent stylesheets, so this topic doesn't need 1500 lines of pasted declarations. scss-build emits artifacts/css/accents/.css and the whole dist/css tree is published with the devextreme package, so the recipe can be a single link/import after the theme stylesheet:
import 'devextreme/dist/css/dx.fluent-next.blue.light.css'; import 'devextreme/dist/css/accents/rose.css';Available files: blue, cool-blue, desert, mint, moss, orchid, purple, rose, rust, steel, storm (blue is already embedded in the theme bundles, so linking it is a no-op). Three details worth stating alongside:
Order matters - the file declares the ramp on :root, exactly like the theme bundle, so it only wins if it comes after the theme (same issue as the "before you load" wording in the intro).
One file covers every mode and size - the primitives are byte-identical in the light, dark and compact bundles, so switching modes means swapping only the theme file, not the accent file.
The file pins all 136 primitives, not just --dxds-primary-* (the 11 palettes differ only in the primary ramp). Harmless, but a user's own primitive overrides must be loaded after it.
Suggested structure: a table of the 11 names + the two-line snippet above, and keep the full variable dumps only as an optional "inline the values instead" sample - trimmed to the 18 --dxds-primary-* steps, since the rest is identical across all accents. Note that a file-based accent exists only for these 11 designed palettes; an arbitrary brand color remains the CSS recipe in 10 Custom Accent Colors.md.
|
|
||
| ## Fluent Next Themes | ||
|
|
||
| <div id="fluent-next-themes" class="theme-images"> |
There was a problem hiding this comment.
The Fluent Next block reuses the Fluent screenshots (fluent-default.png, fluent-compact.png, fluent-dark-default.png, fluent-dark-compact.png) - the same four images as the Fluent section below, so both themes look identical on this page. Are the Fluent Next captures still pending?
|
|
||
| The method accepts the `data-theme` attribute value. For example, if you want to switch to `dx.generic.dark`, pass `generic.dark` (without the 'dx' prefix) as an argument in the method. For a custom theme, specify the theme you used as a base. If both of your themes are derived from the same base, get the `data-theme` value from the `font-family` value of the `dx-theme-marker` CSS class, which is located in each theme's CSS file. | ||
|
|
||
| [note] If you use an accent color stylesheet with Fluent Next themes, you do not need to switch the accent stylesheet when switching themes. These stylesheets apply to all variations of Fluent Next (light and dark modes, standard and compact sizes). Refer to the following help topic for more information about accent colors in Fluent Next themes: [Fluent Next Theme Customization - Accent Colors](/Documentation/Guide/Themes_and_Styles/Fluent_Next_Theme_Customization/#Accent_Colors). |
There was a problem hiding this comment.
Correct, with one condition worth spelling out: DevExtreme replaces all rel="dx-theme" links with a single inserted at the position of the last dx-theme link and then only swaps its href ($allThemeLinks.last().after($activeThemeLink); $allThemeLinks.remove(); in themes.ts). So the accent stylesheet keeps working across switches only if its comes after the whole dx-theme block - placed before or among them, it silently loses the cascade. Worth adding to the note and showing in the snippet.
|
|
||
| <!-- tab: Non-Modular Application --> | ||
| <link rel="stylesheet" href="node_modules/devextreme/dist/css/dx.fluent-next.blue.light.css"></link> | ||
| <link rel="stylesheet" href="node_modules/devextreme/dist/css/accents/rose.css"></link> |
There was a problem hiding this comment.
[validate it] is a void element - drop the closing tags in the non-modular sample.
| Design System CSS variables that serve as public APIs. Use these variables to customize your DevExtreme-powered application. | ||
|
|
||
| - `--dx-*` | ||
| Internal CSS variables and classes used by DevExtreme components. May change between versions. |
There was a problem hiding this comment.
The recommendation below now correctly mentions variables only, but this bullet still reads "Internal CSS variables and classes", which contradicts 00 Styling Overview/10 CSS Styles.md (it recommends using DevExtreme CSS classes and links to the public CSS Classes reference). Suggest dropping "and classes" here.
| @@ -0,0 +1,213 @@ | |||
| Fluent Next themes ship with CSS variables defined in the DevExpress Design System. Refer to the following help topics for additional information about key styling principles and a list of available CSS variables: | |||
There was a problem hiding this comment.
Heads-up: the base branch moved to design tokens 262.10.1 on Aug 26 (07fad6c7f8), which renamed the semantic color tokens to a shorter grammar, and the old names are gone from the product - zero occurrences of color-surface-, -default-rest, color-content-neutral or utility-yellow remain in packages/devextreme-scss/scss and apps/demos/Demos, and there are no aliases (the demos were rewritten in b2f401141e). Every semantic color variable in this topic is a pre-262.10.1 name, so the snippets will silently do nothing (an unknown custom property is invalid at computed-value time and resolves to unset). Mapping for the names used here:
--dxds-color-surface-neutral-default-rest → --dxds-color-bg
--dxds-color-surface-neutral-default-hovered → --dxds-color-bg-hovered
--dxds-color-surface-neutral-default-inverted-rest → --dxds-color-bg-inverted
--dxds-color-content-neutral-default-rest → --dxds-color-content
--dxds-color-content-neutral-default-inverted-rest → --dxds-color-content-inverted
--dxds-color-border-neutral-default-rest → --dxds-color-border
--dxds-color-border-neutral-default-hovered → --dxds-color-border-hovered
--dxds-color-border-neutral-default-inverted-rest → --dxds-color-border-inverted (pattern-based; the theme doesn't consume it, so please confirm against the package)
--dxds-color-surface-primary-default-rest → --dxds-color-bg-primary
--dxds-color-content-primary-default-rest → --dxds-color-content-primary
--dxds-color-border-primary-default-rest → --dxds-color-border-primary
--dxds-utility-yellow-40/50/60 - needs a decision: utility-* no longer appears anywhere in the product, and the semantic equivalents are now --dxds-color-bg-yellow, --dxds-color-bg-yellow-subtle, --dxds-color-content-yellow. Using the semantic yellow roles here would also be more consistent with the rest of the topic.
The scales in the .info-card sample (--dxds-spacing-*, --dxds-border-width-10, --dxds-border-radius-40, --dxds-font-size-base-md, --dxds-line-height-base-md, --dxds-box-shadow-sm) and the whole Accent Colors section (--dxds-primary-10…180) are unaffected - no changes needed there.
One more coordination point: the DS pages linked at the top still document the old grammar (405706 has 308 --dxds-color-surface-* references and no --dxds-color-bg; 405687 documents --dxds-utility-*), so readers who follow those links will get names that don't exist in 26.2. Worth syncing with the Design System doc update before publishing.
| @@ -0,0 +1 @@ | |||
| Fluent Next themes are based on the DevExpress Design System and support multiple customization options. | |||
There was a problem hiding this comment.
Could we specify that Fluent Next themes are based on the Design System Foundation and add a link to the corresponding documentation?
Suggested wording:
Fluent Next themes are based on the Design System Foundation and support multiple customization options.
| @@ -0,0 +1,314 @@ | |||
| Fluent Next themes ship with 11 predefined accent colors. To apply one of these colors, import an accent stylesheet after the theme: | |||
There was a problem hiding this comment.
These predefined colors are part of the DevExpress Design System Foundation. Could we link to the source palettes and clarify the relationship between the Design System's primary color palettes and DevExtreme accent colors?
Suggested wording:
The DevExpress Design System defines 11 predefined primary color palettes for Fluent themes. To use one of these palettes as the accent color in a Fluent Next theme, import the corresponding accent stylesheet after the theme stylesheet:
5 participants
No description provided.