Project

ChartForgeX

Render deterministic charts, dashboards, topology, hierarchy, and report visuals directly from .NET.

View on GitHub Releases Get package
Stars 47
Forks 2
NuGet downloads 75,067
Release ChartForgeX-v2.0.0
Language: HTML Updated: 2026-10-12

API Reference

Class

SvgColorVariables

Namespace ChartForgeX.Themes
Assembly ChartForgeX
Modifiers sealed

Maps colours to CSS custom properties so SVG output can follow a host's design tokens: every paint value (fill, stroke, stop-color, flood-color, lighting-color, color, in attributes, style attributes, and <style> elements) whose colour is mapped is written as var(--name, #rrggbb), with the literal colour as the fallback, so the SVG looks the same where the property is not defined. A paint more transparent than its variable is written as color-mix(in srgb, var(--name, #rrggbb) N%, transparent). PNG output is not affected.

Inheritance

  • Object
  • SvgColorVariables

Remarks

Set on a chart, grid, or topology (Chart.WithSvgColorVariables, ChartGrid.WithSvgColorVariables, TopologyRenderOptions.SvgColorVariables), the renderers write colours by role. A colour the renderer derives (the white sheen of a line, the highlight of a surface, the contrast stroke of a topology icon) stays literal even when it equals a token colour. A blend of token colours (bar gradients, heatmap and calendar ramp steps, neutral zero and empty days, topology tints) is written as color-mix(in srgb, …) of their properties, so it follows a theme switch. A colour written for a role (a series, a status, a ramp step, the surface behind marks) takes the variable of that role when several share its colour. Text on filled marks (heatmap and hexbin values, categorical cell text, Gantt lane labels) is written as the text colour or, on strong marks, the surface behind the marks, by role. Other paints match by colour value. on finished markup only matches by colour value (red, green, and blue; a paint is only matched when it is no more opaque than the variable): every paint of a mapped colour takes the variable, including derived colours that happen to equal it. When two variables share a colour, the one added first is used, and variables are not used for text fills. Do not apply variables to SVG rendered with variables: its derived colours are literal on purpose and would be mapped by value. Roles tell token kinds apart (a series colour from a ramp step of the same value), not tokens within a kind: when two surface tokens share a colour in one theme, the one added first names it.

Usage

Explore 11 API references to this type

This type appears in these public API surfaces even when no hand-authored example is attached directly to the page.

Returned or exposed by 8

Accepted by parameters 3

Constructors

public SvgColorVariables() #

Methods

public SvgColorVariables Add(String name, ChartColor color, SvgColorRole role = Any) #
Returns: SvgColorVariables

Adds a variable. When a variable for the same colour was added before, that one keeps the colour for paints without a role and this one is only used by paints of its own role.

Parameters

name System.String requiredposition: 0
The custom property name, for example --brand-series-1.
color ChartForgeX.Primitives.ChartColor requiredposition: 1
The colour it stands for; its literal value is the fallback.
role ChartForgeX.Themes.SvgColorRole = Any optionalposition: 2
The role of the colour; SvgColorRole.Surface keeps text fills of this colour literal when they are matched by value.

Returns

The same instance.

Exceptions

  • ArgumentException – The name is not -- followed by letters, digits, -, or _.
  • ArgumentOutOfRangeException – The role is not defined.
public SvgColorVariables AddInk(String name, ChartColor fill, ChartColor ink, SvgColorRole fillRole) #
Returns: SvgColorVariables

Adds the contrasting text property paired with a filled mark. The renderer selects this property by the fill, so black or white text follows that mark when the host switches themes, without changing unrelated text.

Parameters

name System.String requiredposition: 0
The CSS custom property for the ink, for example --cfx-series-1-ink.
fill ChartForgeX.Primitives.ChartColor requiredposition: 1
The opaque mark colour in this theme.
ink ChartForgeX.Primitives.ChartColor requiredposition: 2
The contrasting text colour in this theme.
fillRole ChartForgeX.Themes.SvgColorRole requiredposition: 3
The role of the filled mark.

Returns

The same instance.

Exceptions

  • ArgumentException – The property name is invalid.
  • ArgumentOutOfRangeException – The role is not defined.
public String Apply(String svg) #
Returns: String

Writes mapped paint values in finished svg as custom properties, by colour value. Applying it twice changes nothing more. Renderers given these variables also write derived colours by role (see remarks).

Parameters

svg System.String requiredposition: 0
SVG markup, for example from ToSvg().

Returns

The markup with mapped paints replaced.

public SvgColorVariables Clone() #
Returns: SvgColorVariables

Creates an independent copy.

public IReadOnlyList<SvgColorVariable> GetVariablesForSvg(String svg) #
Returns: IReadOnlyList<SvgColorVariable>

Gets this theme's colour variables and the contrasting inks required by the supplied SVG.

Parameters

svg System.String requiredposition: 0
An SVG exported with colour variables enabled.

Returns

The base variables followed by the referenced derived ink variables, evaluated in this theme.

Properties

public IReadOnlyList<SvgColorVariable> Variables { get; } #

Gets the variables in the order they were added.