Is there a way to set the scrollbar color of ScrollablePanelControl and MultilineEditControl?

[changlv]

I cannot find any related configuration options. Have I overlooked anything?

[nickprotop]

Great question — and the answer was split between the two controls, but it's now consistent on master:

MultilineEditControl — already supported. Set the track and thumb colors via the builder or the properties:

Controls.MultilineEdit()
    .WithScrollbarColors(trackColor: Color.Grey23, thumbColor: Color.Cyan1)
    .Build();

// or directly (raises INPC, so it plays nicely with binding):
editControl.ScrollbarColor = Color.Grey23;       // track
editControl.ScrollbarThumbColor = Color.Cyan1;   // thumb

ScrollablePanelControl — you weren't missing anything; it genuinely had no option. Its scrollbar colors were hardcoded. I've just added the matching API (commit 4a1a880, on master) so the two controls are now consistent:

Controls.ScrollablePanel()
    .WithScrollbarColors(trackColor: Color.Grey23, thumbColor: Color.Cyan1)
    .Build();

// or directly:
panel.ScrollbarColor = Color.Grey23;        // track
panel.ScrollbarThumbColor = Color.Cyan1;    // thumb

Both are Color? — leave them unset (null) and you get the existing built-in focus-aware default (cyan thumb / grey track when focused, dimmer when not); set them to override. The thumb color covers both the handle and the up/down (and left/right) arrows.

This is on master now and will be in the next NuGet release. If you build from master and it doesn't behave as you expect, let me know.

[changlv]

@nickprotop Looks like you're still awake. My network is acting up right now, so I can't pull the GitHub repo. I'll run the tests later. Thanks for your work!

[changlv]

@nickprotop I think the scrollbar could use the border color by default for consistent visuals.

[nickprotop]

@changlv Two updates, both on master now.

1. Your suggestion is the default. The scrollbar thumb now defaults to the border color, so it matches the control's frame out of the box — focused → active border, unfocused → inactive border. The track defaults to a dim grey (Grey23) so the thumb stays visible against it. In the built-in themes the active border is Cyan1, so this looks the same as before by value, but it's now defined as "follow the border" rather than a hardcoded constant — exactly the consistency you asked for.

2. A correction to my earlier reply — and it's now actually true. I told you MultilineEditControl's ScrollbarColor/ScrollbarThumbColor properties "already work." They didn't — when I looked, the renderer was ignoring them and drawing hardcoded colors. That was a real bug. It's fixed (the properties + WithScrollbarColors(...) builder now feed the renderer), so the snippet I gave you genuinely works on master now. Sorry for the misfire — thanks for prompting the second look.

3. Bonus: you can now set it theme-wide. The scrollbar colors are part of the theme, so instead of setting them per-control you can change them once for the whole app. Themes are mutable, so the direct way is:

windowSystem.Theme.ScrollbarThumbColor = Color.Orange1;   // applies app-wide on next repaint

Or derive a named theme from a built-in one and register it (new Theme.From(...) API, also just landed):

var myTheme = Theme.From(new ModernGrayTheme())
    .WithName("MyTheme")
    .With(t =>
    {
        t.ScrollbarThumbColor = Color.Orange1;            // focused thumb
        t.ScrollbarThumbUnfocusedColor = Color.Grey50;    // unfocused thumb
        t.ScrollbarTrackColor = Color.Grey23;             // track
    })
    .Build();

windowSystem.ThemeRegistryService.RegisterTheme("MyTheme", "My theme", () => myTheme);
windowSystem.ThemeStateService.SwitchTheme("MyTheme");

Resolution order per control is: instance override (panel.ScrollbarThumbColor = …) → theme (focus-aware) → built-in fallback. So a per-control set still wins where you want a one-off.

All on master, ships in the next NuGet release.

[changlv]

@nickprotop To be honest, when I tried to customize themes by implementing class DemoTheme : ITheme, I felt overwhelmed by the lengthy list of options.

For now, I've created my own ThemeHelper and apply styles during the BuildUI process as a workaround.

public static partial class ThemeHelper
{

    public static readonly List<ThemeColors> Themes = [new ThemeColors(), new DarkThemeColors() ];

    public static ThemeColors Current { get; set; } = Themes[1];
}



public class ThemeColors
{
    public virtual string Name => "Light";


    public virtual Color WhiteColor => ColorHelper.FromHex("#FFFFFF");

    public virtual Color Gray100Color => ColorHelper.FromHex("#F8F9FA");

    public virtual Color Gray200Color => ColorHelper.FromHex("#E9ECEF");

    public virtual Color Gray300Color => ColorHelper.FromHex("#DEE2E6");

    public virtual Color Gray400Color => ColorHelper.FromHex("#CED4DA");

    public virtual Color Gray500Color => ColorHelper.FromHex("#ADB5BD");

    public virtual Color Gray600Color => ColorHelper.FromHex("#6C757D");

    public virtual Color Gray700Color => ColorHelper.FromHex("#495057");

    public virtual Color Gray800Color => ColorHelper.FromHex("#343A40");

    public virtual Color Gray900Color => ColorHelper.FromHex("#212529");

    public virtual Color BlackColor => ColorHelper.FromHex("#000000");



    public virtual Color BodyColor => BlackColor;
    public virtual Color BodyBgColor => WhiteColor;


    public virtual Color PrimaryColor => ColorHelper.FromHex("#0D6EFD");
    public virtual Color SecondaryColor => Gray600Color;
    public virtual Color TertiaryColor => SecondaryColor;
    public virtual Color InfoColor => ColorHelper.FromHex("#0DCAF0");
    public virtual Color SuccessColor => ColorHelper.FromHex("#198754");
    public virtual Color WarningColor => ColorHelper.FromHex("#FFC107");
    public virtual Color DangerColor => ColorHelper.FromHex("#DC3545");
    public virtual Color LightColor => WhiteColor;
    public virtual Color DarkColor => BlackColor;


    public virtual Color PrimaryTextColor => PrimaryColor.ShadeRGB(0.6);
    public virtual Color SecondaryTextColor => SecondaryColor.ShadeRGB(0.6);
    public virtual Color TertiaryTextColor => SecondaryTextColor;
    public virtual Color InfoTextColor => InfoColor.ShadeRGB(0.6);
    public virtual Color SuccessTextColor => SuccessColor.ShadeRGB(0.6);
    public virtual Color WarningTextColor => WarningColor.ShadeRGB(0.6);
    public virtual Color DangerTextColor => DangerColor.ShadeRGB(0.6);
    public virtual Color LightTextColor => WhiteColor;
    public virtual Color DarkTextColor => BlackColor;


    public virtual Color PrimaryBgColor => PrimaryColor.ShadeRGB(0.8);
    public virtual Color SecondaryBgColor => SecondaryColor.ShadeRGB(0.8);
    public virtual Color TertiaryBgColor => SecondaryBgColor;
    public virtual Color InfoBgColor => InfoColor.ShadeRGB(0.8);
    public virtual Color SuccessBgColor => SuccessColor.ShadeRGB(0.8);
    public virtual Color WarningBgColor => WarningColor.ShadeRGB(0.8);
    public virtual Color DangerBgColor => DangerColor.ShadeRGB(0.8);
    public virtual Color LightBgColor => WhiteColor;
    public virtual Color DarkBgColor => BlackColor;


    public virtual Color TextOnPrimaryColor => WhiteColor;
    public virtual Color TextOnSecondaryColor => Gray200Color;
    public virtual Color TextOnTertiaryColor => Gray400Color;
    public virtual Color TextOnInfoColor => WhiteColor;
    public virtual Color TextOnSuccessColor => WhiteColor;
    public virtual Color TextOnWarningColor => WhiteColor;
    public virtual Color TextOnDangerColor => WhiteColor;
    public virtual Color TextOnLightColor => BlackColor;
    public virtual Color TextOnDarkColor => WhiteColor;



    public virtual Color PrimaryBorderColor => PrimaryColor.TintRGB(0.6);
    public virtual Color SecondaryBorderColor => SecondaryColor.TintRGB(0.6);
    public virtual Color TertiaryBorderColor => SecondaryBorderColor;
    public virtual Color InfoBorderColor => InfoColor.TintRGB(0.6);
    public virtual Color SuccessBorderColor => InfoColor.TintRGB(0.6);
    public virtual Color WarningBorderColor => WarningColor.TintRGB(0.6);
    public virtual Color DangerBorderColor => DangerColor.TintRGB(0.6);
    public virtual Color LightBorderColor => Gray200Color;
    public virtual Color DarkBorderColor => Gray800Color;
}

public class DarkThemeColors : ThemeColors
{
    public override string Name => "Dark";


    public override Color BodyColor => Gray300Color;
    public override Color BodyBgColor => Gray900Color;


    public override Color SuccessColor => ColorHelper.FromHex("#6ECC54");

    public override Color PrimaryTextColor => PrimaryColor.TintRGB(0.4);
    public override Color SecondaryTextColor => SecondaryColor.TintRGB(0.4);
    public override Color TertiaryTextColor => SecondaryTextColor;
    public override Color InfoTextColor => InfoColor.TintRGB(0.4);

    public override Color SuccessTextColor => SuccessColor.TintRGB(0.4);
    public override Color WarningTextColor => WarningColor.TintRGB(0.4);
    public override Color DangerTextColor => DangerColor.TintRGB(0.4);
    public override Color LightTextColor => WhiteColor;
    public override Color DarkTextColor => BlackColor;


    public override Color PrimaryBgColor => PrimaryColor.ShadeRGB(0.8);
    public override Color SecondaryBgColor => SecondaryColor.ShadeRGB(0.8);
    public override Color TertiaryBgColor => SecondaryBgColor;
    public override Color InfoBgColor => InfoColor.ShadeRGB(0.8);
    public override Color SuccessBgColor => SuccessColor.ShadeRGB(0.8);
    public override Color WarningBgColor => WarningColor.ShadeRGB(0.8);
    public override Color DangerBgColor => DangerColor.ShadeRGB(0.8);
    public override Color LightBgColor => WhiteColor;
    public override Color DarkBgColor => BlackColor;


    public override Color TextOnPrimaryColor => WhiteColor;
    public override Color TextOnSecondaryColor => Gray200Color;
    public override Color TextOnTertiaryColor => Gray400Color;
    public override Color TextOnInfoColor => BlackColor;
    public override Color TextOnSuccessColor => WhiteColor;
    public override Color TextOnWarningColor => BlackColor;
    public override Color TextOnDangerColor => WhiteColor;
    public override Color TextOnLightColor => BlackColor;
    public override Color TextOnDarkColor => WhiteColor;



    public override Color PrimaryBorderColor => PrimaryColor.ShadeRGB(0.4);
    public override Color SecondaryBorderColor => SecondaryColor.ShadeRGB(0.4);
    public override Color TertiaryBorderColor => SecondaryBorderColor;
    public override Color InfoBorderColor => InfoColor.ShadeRGB(0.4);
    public override Color SuccessBorderColor => SuccessColor.ShadeRGB(0.4);
    public override Color WarningBorderColor => WarningColor.ShadeRGB(0.4);
    public override Color DangerBorderColor => DangerColor.ShadeRGB(0.4);
    public override Color LightBorderColor => Gray700Color;
    public override Color DarkBorderColor => Gray800Color;
}

public static partial class ColorHelper
{
    public static Color FromHex(string hex)
    {
        if(Color.TryFromHex(hex, out var color)) return color;
        throw new ArgumentException();
    }

    public static string WrapMarkup(this string text, Color textColor)
    {
        if (string.IsNullOrEmpty(text)) return text;

        return $"[{textColor.ToMarkup()}]{Spectre.Console.AnsiMarkup.Escape(text)}[/]";
    }

    public static string WrapMarkup(this string text, Color textColor, Color bgColor)
    {
        if(string.IsNullOrEmpty(text)) return text;

        return $"[{textColor.ToMarkup()} on {bgColor.ToMarkup()}]{Spectre.Console.AnsiMarkup.Escape(text)}[/]";
    }

    public static Color MixRGB(this Color color1, Color color2, double weight = 0.5, bool mixAlpha = false)
    {
        weight = Math.Clamp(weight, 0.0, 1.0);

        double r = color1.R * (1 - weight) + color2.R * weight;
        double g = color1.G * (1 - weight) + color2.G * weight;
        double b = color1.B * (1 - weight) + color2.B * weight;

        byte rb = (byte)Math.Round(r);
        byte gb = (byte)Math.Round(g);
        byte bb = (byte)Math.Round(b);

        if (mixAlpha)
        {
            double a = color1.A * (1 - weight) + color2.A * weight;
            byte ab = (byte)Math.Round(a);
            return new Color(rb, gb, bb, ab);
        }

        return new Color(rb, gb, bb, color1.A);
    }

    public static Color WithAlpha(this Color color, double alpha)
    {
        alpha = Math.Clamp(alpha, 0.0, 1.0);

        byte a = (byte)Math.Round(alpha * 255.0);

        return new Color(color.R, color.G, color.B, a);
    }

    public static Color TintRGB(this Color color, double weight, bool withAlpha = false) => MixRGB(ColorHelper.FromHex("#FFFFFF"), color, weight, withAlpha);

    public static Color ShadeRGB(this Color color, double weight, bool withAlpha = false) => MixRGB(ColorHelper.FromHex("#000000"), color, weight, withAlpha);

    public static Color ShiftRGB(this Color color, double weight, bool withAlpha = false) => weight >= 0 ? ShadeRGB(color, weight, withAlpha) : TintRGB(color, -weight, withAlpha);
}

The advantage of this approach is that secondary colors only need to be calculated. Basically, you only need to define the PrimaryColor to switch to an entirely new theme instantly.

For example:

public class MyThemeColors : DarkThemeColors
{
    public override string Name => "MyDarkTheme";

    public override Color PrimaryColor => ColorHelper.FromHex("#FD7E14");
}

[nickprotop]

@changlv That's a really nice approach — deriving a whole coherent theme from one color via tint/shade is much nicer than filling in a flat list. Thanks for sharing the code.

Quick note first: you don't have to implement ITheme from scratch anymore. There's a new Theme.From(...) on master that copies a base theme and lets you override just what you want:

var myDark = Theme.From(new ModernGrayTheme())
    .With(t => t.ActiveBorderForegroundColor = ColorHelper.FromHex("#FD7E14"))
    .Build();

But what you've actually built is better — a theme generator. So I'd like to add exactly that: a helper that takes one (or a few) seed colors and produces a ready theme, deriving everything else with tint/shade — your ThemeColors/ColorHelper logic as a built-in:

var theme = Theme.Generate(primary: Color.FromHex("#FD7E14"));
// change one color → whole consistent theme

The output is just a normal theme you register and switch to.

Two questions to shape it:

1. Seeds: is a single primary enough, or do you want a few anchors (e.g. primary + background, or primary + accent)? Your prototype is basically "primary drives it" — want to keep it that minimal?
2. Mapping: which derived colors should drive which UI pieces — borders, buttons, selection, scrollbars, etc.? Your ThemeColors already maps most of this; I'd want the generator to cover the whole control surface so nothing's left at a default.

[changlv]

@nickprotop In fact, Theme.From() does little to ease my worries!

I’m not familiar with where every property of ITheme actually takes effect (and I suspect other developers feel the same way). It’s easy to overlook certain settings, which will surface issues unexpectedly later on.

The current ITheme system is overly complex for me. I’d rather configure colors for each control during UI construction than use ITheme.

My approach follows the practice adopted by many popular modern UI frameworks.

For example, to display an active window, you only need to brighten the primary color; for disabled states, darken it. You can also overlay transparency and similar adjustments.

Nearly all visual scenarios can be covered with just 1 ~ 3 core colors this way.

Furthermore, all your existing controls provide color configuration interfaces, supporting fine-grained Color customization when detailed adjustments are needed.

My ThemeHelper concept borrows ideas from mainstream UI frameworks: define core colors, and calculate all other variant colors programmatically. It lets you quickly build UIs with consistent visual styles.

That’s roughly my idea. Hope my code can bring you some inspiration!

[changlv]

@nickprotop One additional point: I believe the anchor core colors are BodyBgColor, PrimaryColor, SecondaryColor and TertiaryColor. Tweaking these can deliver excellent visual results.

Also, standard color matching best practices state that a visual scheme should use no more than five core colors (preferably no more than three, excluding black, white and gray).

[nickprotop]

@changlv You nailed it — and it shipped. The generator you sketched is in on master now.

You were right about ITheme. A flat wall of ~130 properties is no way to ask someone to build a theme — not everyone survived the WinUI/XAML template mines. Hand-implementing the interface shouldn't be the path. So now it isn't.

Your idea became Theme.FromPalette(...). Give it a small palette — often just a primary and a background — and it derives a complete, contrast-checked theme, exactly your "core colors drive everything" approach:

var theme = Theme.FromPalette(new Palette
{
    Primary    = Color.FromHex("#0D6EFD"),
    Background  = Color.FromHex("#F8F9FA"),
});

windowSystem.ThemeRegistryService.RegisterTheme("MyTheme", "My theme", () => theme);
windowSystem.ThemeStateService.SwitchTheme("MyTheme");

The anchors you called out — background, primary, secondary, tertiary — are all there, plus optional status colors. Anything you omit is derived:

new Palette
{
    Primary    = ...,   // accent: borders, focus, highlights
    Secondary  = ...,   // optional
    Tertiary   = ...,   // optional
    Background = ...,   // surface — everything else is tinted/shaded from it
    // Success / Warning / Danger / Info optional
}

Two things straight from your notes:

• Light/dark is automatic. It reads the background luminance and flips the text — light surface → dark text — so you don't manage that by hand (there's an optional Mode to pin it).
• No invisible text. Every foreground is chosen to contrast against the surface it actually lands on, not a generic default. That was the other half of the win.

It also ships as built-in seed themes so every app gets a ready set out of the box (Ocean, Amber, Forest, Crimson, Slate, and a light Daylight), and your point about controls already exposing per-control Color for fine-tuning still holds — that path is untouched.

One thing I'd value your eye on. You clearly have UI experience, and the part I'm least sure of is the distribution — which derived shade drives which control (which accent goes to selection vs. hover vs. focused border, how disabled states are damped, etc.). Does the mapping read right to you, or are there spots where a different anchor would look better? Your "≤3 core colors, brighten for active / darken for disabled" framing is exactly the lens I want on it. Build from master and let me know.

[changlv]

@nickprotop

I think we should extract the behaviors and appearances that affect colors, as follows:

Behaviors:
Window or control activated, window or control deactivated,
Control enabled, control disabled, control lost focus, control control received focus,

Core appearances:
Text color, background color, border (scrollbar) color

Special-case appearances (used to replace primary colors in specific scenarios):
Info, Success, Warning, Danger (Error)

Thus we can sort out the core colors:
PrimaryColor: Main core color, such as window borders, button background color (or button border color)
SecondaryColor: General secondary color, e.g., background (or border) of cancel buttons
TertiaryColor: Defaults to the secondary color, or can be defined as a second primary color that complements PrimaryColor, acting as a dual-tone matching color in color schemes.

Special colors: For special status scenarios including Info, Success, Warning, Danger (Error)

Others: Black, white and gray are essential.

Looking forward to the new release! My network connection to github.com is extremely unstable. Pulling the project is unpredictable for me, which is really frustrating.

[nickprotop]

@changlv Your structure matches how the generator is built — behaviors (active/inactive, enabled/disabled, focus), core appearances (text / background / border+scrollbar), and the core colors (Primary, Secondary, Tertiary + Info/Success/Warning/Danger).

What I'd still value your eye on is the concrete mapping — how those core colors actually get assigned to each control. For example, right now: Primary → active border / focused thumb; Secondary → selected-item background (e.g. ButtonSelected, list selection); Tertiary → currently just a darker step of Secondary; disabled → shaded-down + dimmed text; hover → a raised step of the surface. That control-by-control assignment is the part I'm least sure reads "right" to someone with a UI eye, and it's where a different choice (like your complementary second-primary for Tertiary) would change the feel.

So before I publish: does the mapping itself look right to you, or are there controls where you'd pull from a different core color? If it reads well, I'll ship the release; if not, let's adjust the mapping first. I can write out the full color→control table if that helps you judge it.

[changlv]

@nickprotop

Windows and controls shall accept MainColor, [SecondaryColor], [BodyTextColor], [BodyBgColor].

MainColor include: PrimaryColor, TertiaryColor, InfoColor, SuccessColor, WarningColor, DangerColor.

Corresponding colors will be resolved based on the selected MainColor: MainTextColor, MainBackColor, MainTextOnBackColor, MainBorderColor.

Color variants are calculated from the base MainColor for the following states: window/control activated, window/control deactivated, control enabled, control disabled, control lost focus, control received focus.

Example:

// --- Window --- //
Window.BodyBgColor = BodyBgColor;
Window.TextColor = BodyTextColor; // or MainTextColor;

Window.TitleTextColor = MainTextOnBackColor; // or MainTextColor
Window.TitleTextBgColor = MainBackColor; // or BodyBgColor
Window.TitleTextUnfocusColor = MainTextOnBackColor.ShadeRGB(); // or MainTextColor.ShadeRGB();
Window.TitleTextUnfocusBgColor = MainBackColor.ShadeRGB(); // or BodyBgColor.ShadeRGB();

Window.BorderColor = MainBorderColor;
Window.BorderUnfocusColor = MainBorderColor.ShadeRGB();

Window.ScrollColor = MainBorderColor;
Window.ScrollUnfocusColor =MainBorderColor.ShadeRGB();

// --- PrimaryButton --- //
PrimaryButton.TextColor = MainTextOnBackColor;
PrimaryButton.BgColor = MainBackColor;
PrimaryButton.BoderColor = MainBorderColor;

PrimaryButton.FocusTextColor =MainTextOnBackColor.InitRGB();
PrimaryButton.FocusBgColor =MainBackColor.InitRGB(); // or MainBackColor
PrimaryButton.FocusBoderColor = MainBorderColor;

PrimaryButton.DisableTextColor = MainTextOnBackColor.WithAlpha(); // or ShadeRGB()
PrimaryButton.DisableBgColor = MainBackColor.WithAlpha(); // or ShadeRGB()
PrimaryButton.DisableBoderColor = MainBorderColor;

// --- SecondaryButton --- //
SecondaryButton.TextColor = SecondaryTextOnBackColor;
SecondaryButton.BgColor = SecondaryBgColor;
SecondaryButton.BoderColor = SecondaryBorderColor;

SecondaryButton.FocusTextColor = SecondaryTextOnBackColor.InitRGB();
SecondaryButton.FocusBgColor =SecondaryBgColor.InitRGB(); // or SecondaryBgColor
SecondaryButton.FoucsBoderColor = SecondaryBorderColor;

SecondaryButton.DisableTextColor = SecondaryTextOnBackColor.WithAlpha(); // or ShadeRGB()
SecondaryButton.DisableBgColor = SecondaryBgColor.WithAlpha(); // or ShadeRGB()
SecondaryButton.DisableBoderColor = SecondaryBoderColor;

// --- OutlineButton (Drak Theme) --- //
OutlineButton.TextColor = MainTextColor;
OutlineButton.BgColor = BodyBgColor
OutlineButton.BorderColor = MainBorderColor;

OutlineButton.FocusTextColor =MainTextColor.InitRGB();  // or MainTextColor
OutlineButton.FocusBbColor = BodyBgColor;
OutlineButton.FocusBorderColor = MainBorderColor.InitRGB();  

OutlineButton.DisableTextColor = MainTextOnBackColor.WithAlpha(); // or ShadeRGB()
OutlineButton.DisableBbColor = BodyBgColor;
OutlineButton.DisableBorderColor = MainBorderColor.WithAlpha(); // or ShadeRGB()


// --- NotifyMessage --- //
NotifyMessage.TextColor = MainTextColor;
NotifyMessage.BackColor = BodyBgColor;

// --- HeavyNotifyMessage --- //
HeavyNotifyMessage.TextColor = MainTextOnBackColor;
HeavyNotifyMessage.BackColor = MainBackColor;

// --- Dialog --- //
Dialog.BodyBgColor = BodyBgColor;
Dialog.TextColor = MainTextColor;

Dialog.TitleTextColor = MainTextOnBackColor; // or MainTextColor
Dialog.TitleTextBgColor = MainBackColor; // or BodyBgColor

Dialog.BorderColor = MainBorderColor;
Dialog.ScrollColor = MainBorderColor;

Whether the visual effect looks good should be determined by the definition of core colors; the variants only need to have distinguishable differences visible to the naked eye.

I wonder if the examples I provided have answered your questions ?

[nickprotop]

This was really helpful, changlv — thank you. Your "core colors drive everything" framing is what turned FromPalette from an idea into something concrete, and it's already paid off: the library now ships six themes generated straight from that approach — Ocean, Amber, Forest, Crimson, Slate, and Daylight — each defined by just a primary + background, with everything else derived. So your contribution is literally in every one of them. Much appreciated.

On your table: the good news is the generator already implements most of it. Let me map it against what's on master so you can see where we agree and where the real open decision is.

Already matching your model (FromPalette derives all of this from the core colors):

• Window border = accent, unfocused = shaded — ActiveBorderForegroundColor is the primary (contrast-guaranteed against the background); inactive is a shaded neutral. Exactly your BorderColor = MainBorderColor / BorderUnfocusColor = MainBorderColor.ShadeRGB().
• Scrollbar = border color, unfocused shaded — ScrollbarThumbColor = the accent, ScrollbarThumbUnfocusedColor = .Shade(0.4). This is your ScrollColor = MainBorderColor / .ShadeRGB() line verbatim.
• Title focus/unfocus shaded, primary button (bg = primary, text = contrast-on-primary, focused = brightened primary.Tint(0.2), disabled = damped) — all there with the normal/focus/disabled triplet you laid out.
• Contrast-safe text — instead of a fixed text color I derive each foreground to keep a guaranteed luminance gap against the surface it actually lands on, so no invisible text regardless of the seed colors. That's a bit stronger than picking one MainTextColor.

On WithAlpha() for disabled states. SharpConsoleUI is a real compositor with alpha blending: Color has an alpha channel, and windows composite against what's below them. The generator currently damps disabled states with shade/mix toward the background rather than alpha, but your alpha approach is fully viable — it's a reasonable alternative we can use where it reads better. I'll keep that in mind for the disabled-state derivation.

The one real gap — and it's a design decision, not a tweak: your MainColor selector. In your model an individual control can declare which core color drives it (Primary, Tertiary, Info, Success, Warning, Danger) and then resolves its own {Text, Bg, TextOnBg, Border} set plus state variants from that. The generator today bakes a single accent (primary) across the whole surface — status colors only reach notifications/flash, and there's no distinct "secondary button" or "danger button" color family. So SecondaryButton / OutlineButton pulling from SecondaryColor, or a button saying "I'm a Danger button," isn't expressible at the theme level yet.

That's the piece worth deciding on deliberately, because it's additive surface area across every control (a color-role concept), not a mapping change. I don't want to rush it into this release and get the API shape wrong.

So: the scrollbar question that started this thread, plus the palette generator, are shipped and on master. For the MainColor-role idea, I'd like to spin it into its own focused discussion so we can design the role enum + per-control resolution properly — your worked example above is exactly the spec I'd start from. Want me to open that follow-up and credit your table as the starting design?

[nickprotop]

Quick follow-up, changlv — I tried your WithAlpha() idea for disabled states, and it's a really nice effect. Because the renderer composites, a semi-transparent disabled control blends with whatever's behind it and gets a natural greyed-out look that tracks the surface, rather than a flat shaded block.

So it's now the default in the palette generator: disabled buttons, dropdowns, lists, checkboxes, tab headers, and date/time pickers all damp with alpha (~45% opacity) across every palette theme (Ocean, Slate, Daylight, …). One subtlety the contrast audit caught — once the disabled background goes translucent the window shows through it, so the disabled text now reads against the window background rather than the color it sat on when enabled. Keeps it readable on every theme.

There's a new "Disabled States" page in the DemoApp (Controls group) that puts enabled vs. disabled side by side if you want to see it. Thanks again — that's two of your ideas in the generator now.

[changlv]

@nickprotop Regarding the section you mentioned about "The one real gap".

I believe SharpConsoleUI, as a framework, should not dictate how users utilize it.

A theme configuration acts as a theme color palette and provides users with a streamlined decision-making framework.
This prevents users from getting overwhelmed by countless color options.

Regarding the usage of Primary, Tertiary, Info, Success, Warning and Danger:
These should be applied as default values on out-of-the-box components.

For example, use outline buttons consistently in dark themes, warning dialogs, success notifications, error popups, log messages, and so on.

In other words, Tertiary, Info, Success, Warning and Danger need to be set as the default color scheme for specific built-in components.

To address your point about "I'm a Danger button": this styling should be determined by the built-in component's functional purpose.

For instance, users can mark a Dialog as one of Primary / Info / Warning / Success / Danger by configuring:

Dialog.ApplyMainColor = Warning; // default is Primary

Likewise, users may set Spinner.TextColor = SuccessText;.

Alternatively, users can customize colors manually as shown below:

OutlineButton.BgColor = BodyBgColor;
OutlineButton.TextColor = DangerText;
OutlineButton.BorderColor = DangerBorder;


Or to put it more simply:

Button.ApplyMainColor = Success; // Optional, default is Primary
Button.OutlineButton(true); // or Button.ReverseMainColor();,
// I believe `OutlineButton(true)` expresses the behavior more clearly than `ReverseMainColor()`.

To reiterate: A theme is a color palette, is default colors, It provides colors that users can quickly access.

Your responsibility is simply to provide users with this streamlined color palette.

Ultimately, as long as we deliver polished out-of-the-box visual styles, users can customize the colors later to match their own requirements.

I’m not sure if my explanation resolves your confusion.

[changlv]

@nickprotop You’ve understood my point, but the implementation approach may be overly rigid. I’ll provide a snippet of code for your reference.

public class ThemeSettings
{
    public Color Foreground { get; set; }

    public Color Background { get; set; }

    public Color Primary { get; set; }

    public Color Secondary { get; set; }

    public Color Tertiary { get; set; }

    public Color Success { get; set; }

    public Color Warning { get; set; }
    
    public Color Danger { get; set; }
    
    public Color Info { get; set; }
}

public enum ColorPaletteMode
{
    Dark, // default in console app
    Light
}

public class ColorPalette
{
    public Color MainColor { get; private set; }

    public Color TextColr { get; private set; }

    public Color BackColor { get; private set; }

    public Color BorderColor { get; private set; }

    public Color DimTextColr { get; private set; }

    public Color TextOnMainColor { get; private set; }

    // other colors ...

    public ColorPaletteMode Mode { get; private set; }

    public ColorPalette(Color mainColor, Color? foreColor, Color? backColor, ColorPaletteMode mode = ColorPaletteMode.Dark)
    {
        MainColor = mainColor;
        Mode = mode;
        GenColors(mainColor, foreColor, backColor);
    }

    private void GenColors(Color mainColor, Color? foreColor, Color? backColor)
    {
        TextColr = foreColor ?? (Mode == ColorPaletteMode.Dark ? new Color(255, 255, 255) : new Color(0, 0, 0));
        BackColor = backColor ?? (Mode == ColorPaletteMode.Dark ? new Color(0, 0, 0) : new Color(255, 255, 255));
        BorderColor = Mode == ColorPaletteMode.Dark ? MainColor.MixRGB() : MainColor.MixRGB();
        DimTextColr = Mode == ColorPaletteMode.Dark ? MainColor.MixRGB() : MainColor.MixRGB();
        TextOnMainColor = Mode == ColorPaletteMode.Dark ? new Color(255, 255, 255) : new Color(0, 0, 0);

        // other colors ...
    }

}

public class ButtonBuilder
{
    private Color? _backgroundColor;
    private Color? _foregroundColor;
    private Color? _focusedBackgroundColor;
    private Color? _focusedForegroundColor;
    private Color? _disabledBackgroundColor;
    private Color? _disabledForegroundColor;
    private Color? _borderColor;
    private Color? _borderBackgroundColor;

    private ColorPalette? colorPalette;

    public void ApplyMainColor(Color mainColor)
    {
        colorPalette = new ColorPalette(Theme.Current.Settings.Primary, Theme.Current.Settings.Foreground, Theme.Current.Settings.Background);

        _backgroundColor = colorPalette.BackColor;
        _foregroundColor = colorPalette.TextColr;
        _borderColor = colorPalette.BorderColor;

        // set other colors .....
    }
}

Use example

var dialog = new WindowBuilder(ws)
    .ApplyMainColor(ThemeSettings.Warning)
    .WithTitlt("Are you sure?")
        .Build();

var btn_cancel = Controls.Button()
    .ApplyMainColor(ThemeSettings.Secondary)
    .WithTitlt("Cancel")
    .Build();


var btn_ok = Controls.Button()
    .ApplyMainColor(ThemeSettings.Primary)
    .WithTitlt("OK")
    .Build();

// custom main color
var btn_upgrade = Controls.Button()
    .ApplyMainColor(Color("#6750A4"))
    .WithTitlt("Upgrade")
    .Build();

var btn_submit = Controls.Button()
    .ApplyMainColor(ThemeSettings.Success)
    .WithTitlt("Submit")
    .Build();

var btn_Delete = Controls.Button()
    .ApplyMainColor(ThemeSettings.Danger)
    .WithTitlt("Delete")
    .Build();

// custom palette
var palette = new ColorPalette("#0DCAF0");
var text = Controls.Markup()
        .WithBackgroundColor(palette.MainColor)
        .WithForegroundColor(palette.TextOnMainColor)
        .Build();

The code above is not rigorous, but the core idea is that every control gets access to a ColorPalette and retrieves colors from it as needed.

Limiting roles would be overly rigid.

When a control does not call ApplyMainColor, Primary will be used by default. Unless it is a prebuilt component (has a clear functional behavior, such as warning messages), there is no way to know the purpose the user has defined for this control.

[nickprotop]

Thanks — I think we're closer than it looks: your ColorPalette (derive a coordinated set from a main color + the theme) is exactly what the role resolver does internally. The only real difference is the input — I keyed it on a closed ControlRole enum; you'd key it on any Color.

Your example shows two things, and I want to solve the right one:

1. Semantic roles — Warning/Success/Danger. These work today (WithRole(ControlRole.Warning)) and are theme-aware: switch Ocean → Daylight and a Danger button re-derives automatically.
2. An arbitrary brand color — ApplyMainColor(Color("#6750A4")) for "Upgrade". Roles don't cover this.

The catch with (2): a hardcoded #6750A4 can't be theme-aware — it stays that purple under every theme (the resolver still derives readable text/border on it, but the base is pinned). Fine for a brand color, but a different thing from a semantic role.

If (2) is the ask, it's a clean addition: an overload — WithRole(ControlRole) for semantic, WithRole(Color) for an explicit base — both feeding the same derivation. The enum stays the curated set; the Color overload is the escape hatch.

Same engine either way — it's just whether the door is the 7 roles, any color, or both. Which fits how you'd actually use it?

[changlv]

@nickprotop I believe Role defines colors based on behavior, while ApplyMainColor lets users decide what behavior a given color represents.

I personally prefer the ApplyMainColor approach, as this is something to be determined at the application layer (user code).

Additionally, I have revised the earlier examples.

[changlv]

@nickprotop Users shall take full responsibility for any custom colors they define.

[changlv]

@nickprotop I suddenly realize why you’ve been stuck on this, and why ITheme has over a hundred properties. You’re treating SharpConsoleUI as a complete application and trying to handle everything internally, but SharpConsoleUI is meant to be a framework. Don’t forget there’s an application layer (user code) built on top of it.

[nickprotop]

I think we actually agree more than it looks — and honestly, your roles + generator idea moved this framework forward. Let me reframe with that in mind.

Take WinUI, which I know best: it does declare every color of every control at the low level (the theme resource dictionaries) — and frankly that low level was chaos. Thousands of brush keys, schemes layered on schemes; powerful, but a swamp to work in. A framework needs that completeness — it's how a control knows what to paint — but raw, it's miserable.

What your roles and FromPalette did was separate the two angles cleanly, which is the real step forward:

• The framework keeps its complete, every-aspect theming (controls always know their colors).
• The user never touches it. They set a role, or generate a whole theme from 2-3 colors — done:

// whole theme (~130 colors) from 2 seeds — your idea:
var ocean = Theme.FromPalette(new Palette {
    Primary    = Color.FromHex("#2DD4BF"),
    Background = Color.FromHex("#0B1F2A"),
});
// per control, one method:
new ButtonBuilder().WithText("Delete").WithRole(ControlRole.Danger).Build();

So the ~130 ITheme properties aren't the user's burden — they're the low level your two ideas hide. Nobody sets 130 colors.

And the app can still control everything, exactly like copying a WinUI resource XAML and editing it to the extreme — declare or derive a full theme (Theme.From(...) / a custom ITheme) when it wants total control.

Where you're plainly right is the middle escape hatch: theme a control to its own color, not just the 7 roles — your ApplyMainColor(Color("#6750A4")). That's the WithRole(Color) overload, feeding the same derivation. Glad to add it. So: set a role (easy), give a color (your escape hatch), or own the whole theme (full control) — three tiers, and your work is what made the easy one easy.

[changlv]

@nickprotop Alright, as long as it achieves the desired effect.

Also, does the ApplyMainColor method need to take a ThemeMode parameter?

like: ApplyMainColor(Color color, ThemeMode? mode = null)

[changlv]

@nickprotop Maybe we can rename WithRole to WithColorRole, since the standalone term "Role" is mostly used to represent user roles and permission management.

[changlv]

@nickprotop We can either choose ApplyMainColor or WithRole. Having too many overloaded methods with similar functionality but different names is confusing.

I've noticed SharpConsoleUI currently contains numerous overloaded methods that do nearly the same thing yet bear distinct names.

[changlv]

@nickprotop

Essentially, the system does not require as many colors as one might think.

A Cell fundamentally only needs a foreground color and a background color, which gives us:
ForeColor
BackColor

However, both Text and Border elements use ForeColor, so we need to distinguish them, resulting in:
TextColor
BorderColor
BackColor // TextBackColor and BorderBackColor

Next, we add variants based on control states: Normal, Focused, Disabled, yielding:
TextColor
TextFocusColor
TextDimColor

BorderColor
BorderFocusColor
BorderDimColor

BackColor
BackFocusColor
BackDimColor

Finally, we introduce MainColor plus a special case TextOnMainColor. The complete color palette is as follows:

MainColor
MainFocusColor
MainDimColor

TextColor
TextFocusColor
TextDimColor

BorderColor
BorderFocusColor
BorderDimColor

BackColor
BackFocusColor
BackDimColor

TextOnMainColor
TextOnMainFocusColor
TextOnMainDimColor

Simply retrieve the corresponding color based on the type of displayed content and the current control state. There is no need to define an excessive number of colors at the low level.

[nickprotop]

Good points — and easy call. First, a small clarification: there's no ApplyMainColor in the library, and never was — that was your proposed name. What actually shipped is just two things: FromPalette (generate a theme) and WithRole (style one control). So there's nothing to merge or de-duplicate — there's only ever been one method for this.

On the name: you're right that "Role" carries baggage (permissions/user-roles). I first tried WithStyle/Style, but Style was already taken — SpinnerControl.Style is its animation style. So I'm going with your earlier suggestion, ColorRole / WithColorRole — it disambiguates from permission-roles and sidesteps the clash:

button.WithColorRole(ColorRole.Danger);
button.WithColorRole(ColorRole.Success, ThemeMode.Dark);   // pin dark/light derivation
button.WithColorRole(ColorRole.Warning);                    // mode omitted → inferred from the active theme

One method, WithColorRole, taking a ColorRole (Primary/Secondary/Tertiary/Info/Success/Warning/Danger) and an optional ThemeMode? mode = null. No overloads, no aliases — exactly your "too many similar methods is confusing" point.

On the mode: good call — you keep the control. Pass a ThemeMode to pin dark/light derivation, or leave it null (the default) and the resolver infers it from the active theme. Either way the style stays theme-aware.

Renamed the prerelease WithRole/ControlRole → WithColorRole/ColorRole. Thanks for the naming push — it's the right convention.

[changlv]

@nickprotop If the WithColorRole method respects the active theme, the ThemeMode parameter becomes unnecessary.

[nickprotop]

Two things:

On ThemeMode: I'll keep it — but as you say, it's optional, so we're not in conflict. WithColorRole(ColorRole.Danger) does exactly what you want: respects the active theme, no mode passed. The parameter only exists for the rare case where someone renders a control on a surface that differs from the theme's nominal mode. Null default = your path; the override is just there for whoever needs it. Costs nothing to ignore.

On the color model — you're right, and that's actually how the resolver already works. Your MainColor / Text / Border / Back / TextOnMain × (Normal/Focus/Dim) set is precisely what ColorRoleResolver derives from a single base color: give it one color (the role's, or your own), and it computes the contrast-checked text-on-fill, the border, the focused (brightened) and disabled (alpha-damped) variants. Nobody hand-sets those ~15 — they're derived.

The one place I'd refine your model: in a real compositor, deriving against a dark/light flag is coarser than deriving against the actual surface color. The resolver does the latter — it keeps the text/border at real contrast against the specific background they land on (luminance-checked), not just "dark mode → white text." That's stronger than a fixed TextColor/TextDimColor table, and it's why a Warning role stays readable on Daylight and Ocean without per-theme tuning.

So the ~130 ITheme members aren't 130 decisions — they're the derived output surface (so every control has a concrete color to paint), generated by FromPalette from 2-3 seeds. You give a few colors; the resolver produces the rest, per your model. We're aligned.

[changlv]

@nickprotop Alright, I have no further questions.

Looking forward to the new preview release!

[nickprotop]

Thanks, changlv — your ideas genuinely helped. FromPalette and the color roles made the theming a lot better, and they're in rc.5 now. Appreciate you taking the time on this.