Fluent Next Theme: Add New Topics & Old Topic Updates

[arman-boyakhchyan]

No description provided.

[pharret31]

Actually these variables may be changed as well?

[arman-boyakhchyan]

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.

[EugeniyKiyashko]

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.

[EugeniyKiyashko]

Update after DevExpress/DevExtreme#35275 (viz tokens, merged into the feature branch on Sep 24): the note added to 10 Accent Colors/00 Accent Colors.md (line 3) is no longer accurate for one component. RangeSelector now paints its selected range, slider handles and markers with the accent color - custom or predefined. The other SVG-based components still use palette colors that do not depend on the accent. Suggested wording:

Accent colors in Fluent Next themes apply to HTML-based components and to the RangeSelector selection. Other SVG-based components use palette colors that do not depend on the accent color.

[EugeniyKiyashko]

[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.

[EugeniyKiyashko]

The classes are renamed, thanks. Two leftovers:

• The wrapperAttr samples still use dark-colors-custom (lines 154, 161, 187, 210 and 221), and the topic no longer defines that class - it became .custom-colors-hex above. Copied as is, these samples produce an unstyled overlay.
• .yellow-accent is declared twice in the last snippet, so a reader who copies it gets only the second block. I left a separate comment there, because the colors in that sample have a contrast problem as well.

[alexfi1in]

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.

[alexfi1in]

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:

[EugeniyKiyashko]

This link breaks the "Check links" job: it fails on this PR and passes on the base commit 2fa5c0df2. The log ends in System.Exception: Unknown path thrown from ConvertLinkHelper.GetFilePathForCurrentPath, and this is the only {currentpath} link under concepts/ - elsewhere the token is used in API reference topics only. The absolute form used by the other links in this PR works:

[Custom accent colors](/Documentation/Guide/Themes_and_Styles/Fluent_Next_Theme_Customization/#Accent_Colors/Custom_Accent_Colors)

The converter stops at the exception, so please re-run the check after the fix - links after this one were not validated.

[EugeniyKiyashko]

DevExpress/DevExtreme#35275 (viz tokens, merged into the feature branch on Sep 24) changed this: SVG components now follow container-specific theme modes. A chart inside a dx-theme-mode-dark container draws its background, text, axes, grid, borders and tooltip in dark mode, the tooltip is attached inside a container of the same mode, and an export keeps the container's background. Series and point palette colors are the same in both modes. No refresh call is needed - the markup references CSS variables, so the chart repaints as soon as the class changes. Suggested wording:

• SVG components also follow container-specific theme modes. Palette colors of series and points are the same in both modes.

[EugeniyKiyashko]

Worth one more paragraph here: DevExpress/DevExtreme#35230 added themes.customAccentColor(), the only way to change the accent at runtime without writing CSS, and #9197 documents it in the API reference. A short snippet and a link would connect the two:

DevExpress.ui.themes.customAccentColor('#6b4fbb');
// modular: import { customAccentColor } from 'devextreme/ui/themes';

Two facts a reader of this topic needs: the method sets --dx-accent-color on the document element as an inline style, so it takes priority over a value declared in any stylesheet; null or an empty string removes it, which brings back the stylesheet value or the predefined accent.

The warnings this method logs - W0024 for an invalid color and W0025 for a theme other than Fluent Next - still have DocGen placeholders only (zz Errors and Warnings/W0024.md and W0025.md).

[EugeniyKiyashko]

Both samples render text that cannot be read - the same problem the .dark-colors-custom sample had earlier. --dxds-color-content-yellow is a text color for neutral backgrounds, not for --dxds-color-bg-yellow:

sample	text contrast
utility palette, light mode (#916400 on #eaa300)	2.42:1
utility palette, dark mode (#f9bf62 on #eaa300)	1.30:1
custom colors (#EFB839 on #F2C661)	1.12:1

WCAG AA asks for 4.5:1. Both blocks also share one selector, so a reader who copies the snippet gets only the second one. A variant that reads well (13.99:1 in light mode, 5.22:1 in dark mode, and 8.52:1):

/* Utility palette colors */
.yellow-utility {
    --dxds-color-bg: var(--dxds-color-bg-yellow-subtle);
    --dxds-color-border: var(--dxds-color-border-yellow);
}

/* Custom colors */
.yellow-custom {
    --dxds-color-bg: #F2C661;
    --dxds-color-content: #3F2900;
    --dxds-color-border: #EDAD1C;
}

[EugeniyKiyashko]

Both links are data-active="false". With no active link, DevExtreme applies the first one - dark here - which contradicts step 1 of this topic ("A theme with the data-active attribute set to true is applied"). Suggest data-active="true" on one of them. Minor: the accent path (node_modules/devextreme/dist/css/accents/rose.css) differs from the theme paths (css/...); css/accents/rose.css would match them.

[EugeniyKiyashko]

This holds for --dxds-color-bg-primary, which the theme declares once, on :root. Most color roles work differently: every theme mode class declares its own value (for example, --dxds-color-bg and --dxds-color-content-primary), so a :root override of such a role does not reach elements inside a dx-theme-mode-* container - including a dx-theme-mode-light container on a light page. Since the theme modes topic teaches readers to add these containers, one sentence here would save them the surprise, for example:

Theme mode containers redeclare mode-dependent variables such as --dxds-color-bg. To customize these variables within a container, define the overrides on the container element:

.sidebar.dx-theme-mode-dark {
    --dxds-color-bg: #1f1f1f;
}

[EugeniyKiyashko]

Worth one more bullet here. Fluent Next still declares most of the --dx-* variables that the other themes expose on :root (--dx-color-primary, --dx-color-text, --dx-font-size, ...), each mapped to a --dxds-* variable, and existing topics use them (Chat - Implement an AI Chat Clear Button, First Steps, TileView, Draggable). As written, this bullet tells a reader they are internal and may change. Four of them are not available at the root level in Fluent Next, which is exactly what someone moving from Fluent needs to know. The mapping below is taken from the current feature branch - DevExpress/DevExtreme#35343 finalized the list on Sep 28. It would also cover DevExpress/dxvcs#45486.

Legacy variables in Fluent Next: 34 kept, 4 not available on :root

Colors are declared on :root and on each theme mode class, so they follow container-specific modes:

legacy variable	Fluent Next value
--dx-color-primary	--dxds-color-content-primary
--dx-color-link	--dxds-color-content-primary
--dx-color-success	--dxds-color-content-success
--dx-color-warning	--dxds-color-content-warning
--dx-color-danger	--dxds-color-content-danger
--dx-color-text	--dxds-color-content
--dx-color-icon	--dxds-color-content-subtle
--dx-color-spin-icon	--dxds-color-content-subtle
--dx-texteditor-color-label	--dxds-color-content-subtle
--dx-color-main-bg	--dxds-color-bg-canvas
--dx-component-color-bg	--dxds-color-bg
--dx-datagrid-row-alternation-bg	--dxds-color-bg-low
--dx-color-options-panel-bg	--dxds-color-bg-inverted at --dxds-opacity-5
--dx-color-border	--dxds-color-border
--dx-color-separator	--dxds-color-border-subtle

Sizes are declared on :root. Compact themes use the values in brackets:

legacy variable	Fluent Next value
--dx-font-size	--dxds-font-size-base-md [--dxds-font-size-base-sm]
--dx-font-size-xs	--dxds-font-size-120
--dx-font-size-sm	--dxds-font-size-180 [--dxds-font-size-140]
--dx-font-size-md	--dxds-font-size-200 [--dxds-font-size-160]
--dx-font-size-lg	--dxds-font-size-280 [--dxds-font-size-200]
--dx-font-size-xl	--dxds-spacing-340 (34px; the font size scale has no such step) [--dxds-font-size-240]
--dx-font-size-heading-1	--dxds-font-size-headline-xl [--dxds-font-size-headline-lg]
--dx-font-size-heading-2	--dxds-font-size-headline-lg [--dxds-font-size-headline-md]
--dx-font-size-heading-3	--dxds-font-size-headline-md [--dxds-font-size-headline-sm]
--dx-font-size-heading-4	--dxds-font-size-headline-sm [--dxds-font-size-title-md]
--dx-font-size-heading-5	--dxds-font-size-title-md [--dxds-font-size-title-sm]
--dx-font-size-heading-6	--dxds-font-size-title-sm [--dxds-font-size-title-xs]
--dx-font-size-icon	--dxds-spacing-200 [--dxds-spacing-160]
--dx-component-height	--dxds-spacing-320 [--dxds-spacing-240]
--dx-toolbar-height	--dxds-spacing-480 [--dxds-spacing-360]
--dx-list-item-padding-block	--dxds-spacing-60 [--dxds-spacing-40]
--dx-list-item-padding-inline	--dxds-spacing-120 [--dxds-spacing-80]
--dx-border-radius	--dxds-border-radius-40
--dx-border-width	--dxds-border-width-10

Not available on :root in Fluent Next:

• --dx-color-shadow, --dx-popup-toolbar-item-padding-inline, --dx-texteditor-color-text - not declared.
• --dx-button-padding-inline - declared on buttons only (.dx-button, .dx-dropdowneditor-button), so it is not visible to other elements.

[EugeniyKiyashko]

Heads-up on the linked Design System pages (checked today): 405638, linked here and for "primary shades" in the custom accent topic, shows a 17-step ramp with the base at step 90 (Blue --dxds-primary-90 is #0F6CBD, -100 is #0D64B0), while 26.2 ships 18 steps with the base at step 100 (-90 is #2b7ecf, -100 is #0f6cbd). A reader who takes step numbers from that page overrides the wrong shade - for example, in the --dx-accent-color-90 sample of the custom accent topic. The other linked pages are behind as well: 405706 lists 308 names in the pre-262.10 grammar and none of the names this topic uses, and 405687/405639 document --dxds-utility-*, which 26.2 does not ship. Worth syncing with the Design System docs update (DevExpress/dxvcs#44115) before publishing.

[EugeniyKiyashko]

[minor] SlateBlue here is the accent color itself - step 100 is the source color - so the sample reads as "make shade 90 equal to the base". A distinct value would show the intent better. Line 21: "after" is enough, "immediately after" is not required.

[EugeniyKiyashko]

[minor] DxPopupModule is listed in imports but not imported: import { DxPopupModule } from 'devextreme-angular'; is missing.

[EugeniyKiyashko]

[minor] DxButtonModule is imported but not listed in the component's imports, Component is not imported, and changeThemeMode($event) passes an argument to a method without parameters - an error under strictTemplates.

[EugeniyKiyashko]

[minor] "Each mode is available as a separate stylesheet" next to "All Fluent Next stylesheets ship with both light and dark CSS rules" (container-specific topic) needs the link between them: every stylesheet contains both modes, and the file only sets the page's default mode. This also makes the simplest page-wide switch worth a sentence: toggling dx-theme-mode-dark on <html> switches the whole page without loading another stylesheet.

[EugeniyKiyashko]

[minor] Worth saying that overlays open in the mode of the container that owns them without any call: a popup opened from a dx-theme-mode-dark container renders dark even though it is attached to the viewport. refreshMode() is only needed for overlays that are already open when the class changes.

[EugeniyKiyashko]

[optional] @container style() tests the element's parent, so this rule does not see a mode class set on .my-panel itself. Half a sentence would help: mode-specific rules apply to descendants of the mode container.