NE.Standard

Theming

A theme is a fixed set of tokens configured once on the application builder; a component never invents its own way of being themed. There are three vocabularies for "what does this look like", and every component uses the one its kind is entitled to.

Configuring the theme

ConfigureTheme on the application builder, through UIApplicationThemeBuilder:

application.ConfigureTheme(theme => theme
    .ConfigureLightPalette(palette => palette with { Primary = new ColorVariant(ColorName.AstralTeal) })
    .ConfigureDarkPalette(palette => palette with { Primary = new ColorVariant(ColorName.AstralTeal, ColorAdjustment.Tint, 2) })
    .ConfigureTypography(typography => typography with { FontFamily = "Georgia", CapHeight = 0.69 })
    .ConfigureShape(shape => shape with { CardRadius = UICornerRadius.Uniform(12d) })
);
Method Does
UseTheme(UITheme) replaces the whole theme
UseLightPalette/UseDarkPalette(UIColorPalette) replaces one palette
ConfigureLightPalette/ConfigureDarkPalette(Func<UIColorPalette, UIColorPalette>) edits one palette from its current value
UseTypography/ConfigureTypography replaces or edits UITypography
UseShape/ConfigureShape replaces or edits UIThemeShape
UseLoadingStyle(UILoadingStyle) sets the default loading indicator style (Ring or Dots)

Every token type is a record with init-only members, so ConfigureXxx is always x => x with { ... } over the value passed in. UseTheme/UseLightPalette/etc. validate what they are given and throw if it is invalid.

UITheme

Light and Dark (UIColorPalette, both required), Typography (UITypography), Shape (UIThemeShape), FocusRing (bool, off by default — under forced-colors: none, keyboard focus on buttons, links, rows, list entries and toggles reuses the pointer hover wash and ink step-up rather than drawing a separate outline frame, while forced-colors: active draws a 2 px solid Highlight outline; turning FocusRing on adds a ring for keyboard focus only, never for a pointer press), PressRipple (bool, off by default — when enabled, a wave from the pointer's own position fills a button, an action, a menu or list entry or a row whose press does something while it is held, and fades on release; the web writes data-ui-press-ripple on <html> only while it is on, and respects prefers-reduced-motion), OverlayScrollbars (bool, on by default — where a pointer hovers, a thin thumb is drawn over a scroller's edge while the reader scrolls it and while the pointer nears that edge, a handle to drag, and a scroller's padding on that side is at least --ui-scrollbar-room (12 px), whether or not it overflows; off, the platform's thin bar in the room it keeps; the web writes data-ui-overlay-scrollbars on <html>), and two mark tones (UIMarkTone: Brand, resolved through UIColorPalette.ResolvePrimaryMark() as --ui-color-primary-mark so raw #006E64 stays untouched while pale primaries on light pages shade to 4.5:1 and very dark primaries on dark grounds lift to at least 2.4:1, or Neutral, color-mix(in srgb, var(--ui-color-on-surface) 28%, var(--ui-color-mark))): FieldFocus, a focused or open field's edge and outer halo (Neutral by default); SelectionMark, the line that says chosen and the one that says where a drag would land (Brand by default). UIThemeDefaults.Default is the starting point ConfigureTheme edits from, with LightPalette/DarkPalette/Typography/Shape also reachable individually. The page's head preloads the fonts it draws with — the framework's glyph face, an icon pack's font, and Geist only while the theme's FontFamily names it.

UIColorPalette

One palette per mode. The roles: Primary, Accent, Background, Surface, Info, Warning, Success, Danger, each with an On* counterpart meant to sit on top of it (OnPrimary, OnAccent, OnBackground, OnSurface, OnInfo, OnWarning, OnSuccess, OnDanger); plus Selected, FocusRing, Border, Mark, Shadow, Overlay, and DisabledOpacity (a byte, 0–255, applied to disabled interactive elements). Series (IReadOnlyList<ColorVariant>) is the run of colours a chart's series take in turn, cycled when there are more series than colours; the default eight leave out the warning and danger colours, so a series never reads as a warning or an error. Unset, each of the eight is moved toward the page's text — lifted on a dark palette, deepened on a light one — by the fewest tenths that read 3:1 on that palette's Background and Surface, so a line, a bar or a sector stands off the page and a card in either mode; a palette with grounds of its own draws the run for them, and a Series an application sets is used as given.

Mark is the edge that says a control is there — an Outline field's border, an Underline field's rule, an unchecked checkbox's, radio's or switch's ring, a slider's track — where Border only parts one region from another. It is an explicit ColorVariant on UIColorPalette (#404040 on the default dark palette, #C8C8C4 on the default light palette), and UIThemeColor.Mark names it for an author's own colour. A reader who asks the system for more contrast (prefers-contrast: more) gets every border — a card's edge, a divider, a table's rule — in the mark too.

Six roles also carry an ink variant — PrimaryInk, AccentInk, InfoInk, WarningInk, SuccessInk, DangerInk. The fill (Primary, Info, ...) is what a background or a filled control paints; the ink is what that same colour looks like as text on the page — a label, an icon, a badge's text — read against the page's own ground rather than against the fill's On* counterpart. A status ink (InfoInk, WarningInk, SuccessInk, DangerInk) reads 4.5:1 on a badge tinted with its own colour, over the page and over a card. In the default light palette PrimaryInk, AccentInk and InfoInk equal their fills; WarningInk, SuccessInk and DangerInk are shades of theirs, since a gold light enough to carry dark text is too light to read as text on a light page, and the green and red fell just short on their tinted badges. In the default dark palette it is the other way round: most inks are lighter tints of their fills, so they read on the dark page, and WarningInk equals its fill. A tinted or outlined badge writes its words in --ui-color-<role>-ink-on-tint — the ink pulled toward the text colour, a brand ink 44 % of the way and a status ink 20 % — so the badge reads on its own tint over the page and a card while the ink everywhere else keeps its colour. Change the ink along with the fill when a palette's colour changes.

UITypography and UIThemeShape

UITypography: FontFamily (string, default "Geist" — the web platform ships that face, Latin and Cyrillic, so the default reads the same on every machine; another family is the page's own to provide), CapHeight (double, default 0.71, Geist's — the face's capital height over its size, its OS/2 sCapHeight / unitsPerEm; a theme naming another face sets that face's, between 0 and 1) and six UITextStyle roles — Display, Title, Subtitle, Body, Caption, Overline. Each UITextStyle is FontSize, LineHeight, FontWeight (default 400) and an optional LetterSpacing, all in device-independent pixels (CSS px on the web). The web writes each role's size as the nearest whose capitals stand an even number of whole pixels tall (2 × round(FontSize × CapHeight / 2) / CapHeight: Body 14 is drawn at 14.085 px, 10 px capitals; Caption 12 at 11.268 px, 8 px capitals), so words centred in a control share the middle of the icons beside them; the line height stays as authored.

UIThemeShape: five UICornerRadius tokens — CardRadius, ButtonRadius, InputRadius, RowRadius (default 6, matching buttons and inputs for tables, trees, tab headers and key/value lists), NotificationRadius (square by default for a toast's leading accent stroke).

Naming a colour

UIThemeColor is what a component property takes wherever a colour is themeable — a semantic role tracked live, or a fixed override:

new TextComponent().SetDescriptionColor(UIThemeColor.Muted);
new BadgeComponent().SetColor(UIThemeColor.FromColorVariant(ColorName.AstralTeal, ColorAdjustment.Tint, 2));

UIThemeColor.FromStyle(UIColorStyle) tracks a semantic role (Primary, Danger, Muted, ...) live across a theme change; the static properties (UIThemeColor.Primary, UIThemeColor.Danger, UIThemeColor.Muted, ...) are shorthand for exactly that. FromColorVariant fixes a colour from NE.Colors — a ColorName plus an optional ColorAdjustment, factor and opacity — used identically in both modes; Create(light, dark) gives each mode its own fixed colour. UIColorStyle itself is the full set of semantic roles a UIThemeColor or a palette member can name. UIThemeColor.Transparent is no fill — a colour of no opacity, the same in both modes: a background written it shows what is behind it, and what stands on it takes the page's ink, so a bound background can switch a surface's fill off (a chat's sticker standing without its bubble), and a binding that comes back null returns the component's default.

Muted is measured from the text colour of the ground an element sits on, not from the element's own colour, so muted text inside a region that is already muted does not fade a second time. A component given a Background sets --ui-faint-base to the text colour that reads on that colour, so muted text on a filled panel fades the panel's own ink — less than on the page, so it still reads 4.5:1 on every default fill; a custom surface with a text colour of its own sets --ui-faint-base to it, and muted text on that surface follows. The same component writes --ui-ground to the colour itself (for a transparent one, inherit: the ground around it), so a part cut out of the ground (a chart's hollow marker, the edge between two pie sectors) paints the panel's colour; a custom surface that paints a ground of its own sets --ui-ground to it beside --ui-faint-base. On such a panel a link and the words of a Ghost or Outline button take the panel's text colour too, a link keeping its underline so it still reads as one; a Background of Surface or Background is the page's own ground, and changes none of this.

A component that takes a BackgroundImage (a container, a scroll container, a surface, a card, a button…) can also dim and blur it: BackgroundImageDim from 0 to 1, BackgroundImageBlur in pixels, and BackgroundImageDimMode — Uniform, the default, or Vignette, the edges dimmed and the middle clear, which frames a card or a hero picture rather than giving words a ground to read on. The dim is a veil of the surface's own ground (--ui-ground) laid over the picture — darker in a dark theme, lighter in a light one — so words and child components on the surface stay readable at any dim level. The blur softens the picture alone, under the content and inside the component's edge and corners. All three are drawn by the browser over the picture it already has, so a bound value — a reader's slider for a chat's wallpaper — sends its number and nothing else; a value written in the view outside its range is refused, a bound one held to it.

new ContainerComponent()
    .BindBackgroundImage(nameof(ChatController.Wallpaper))
    .BindBackgroundImageDim(nameof(ChatController.WallpaperDim))
    .BindBackgroundImageBlur(nameof(ChatController.WallpaperBlur))
    .AddChild(messages);

The colour vocabulary

The names themselves come from NE.Colors, a package of its own with no dependencies: thirty-two colours in nine families, each adjustable by a tint or a shade in ten steps and by an opacity.

Family Names
Neutral IronFog SilverNight BronzeDusk
Red / Pink StellarRed NebulaRose LunarPink PulsarMagenta
Orange / Yellow SolarAmber NebulaLemon LunarYellow SolarGold
Olive / Lime EclipseOlive NebulaLime LunarSage
Green AuroraGreen NebulaMint LunarFern
Teal / Cyan AstralTeal NebulaCyan LunarMoss
Blue QuantumBlue NebulaAqua LunarAzure
Purple NovaPurple NebulaViolet LunarLavender
Accent Comet Flare Ember Photon Vortex Halo

A ColorVariant is a name plus an optional ColorAdjustment — Tint towards white, Shade towards black, a factor from 0 to 10 — and an opacity. That is the whole model: new ColorVariant(ColorName.AstralTeal, ColorAdjustment.Tint, 2) is the same colour two steps lighter.

Every colour with its full ramp is rendered in that package's own examples/palette.html, generated from the palette itself. What each name means is documented there rather than here, since the palette is used outside this framework as well.

The three looks

Kind Property Values
What a component is drawn as Variant (UIProgressVariant, UIExpanderVariant, UIFileInputVariant, UIImageInputVariant, UISwitcherVariant, UIMultiSelectVariant) A bar or a ring; an expander's Card (default) or Quiet — a full-row header in 1st-degree muted ink with the chevron right after the title, stepping up to 2nd-degree ink with a hover/focus wash (--ui-wash-hover) protruding outward by its padding; a file input's Row, Tiles or Shelf; an image input's Picture, Avatar or Inline; a switcher's Button or Field; a multi-select's Chips, Badges, Checkboxes or Button
Containers and content-bearing surfaces Surface (UISurfaceStyle) Background — the page's own ground inside a border; Surface — a panel lifted onto --ui-color-surface (#222222 on dark, #E4E4E4 on light); Tinted — the surface's own colour mixed into the mode's ground
Inputs with a field of their own Appearance (UIInputAppearance) Filled (default) — the elevated fill (--ui-field-rest), rounded all round, answering focus with a 1 px contour in FieldFocus plus a 2 px outer halo (--ui-input-focus-ring) and not reacting to hover; Outline — a border all round in the mark, answering focus with the same contour and 2 px halo; Underline — one rule under the text in the mark; Ghost — no fill and no edge at rest, --ui-wash-hover on hover and while focused, stepping text up to --ui-text-selected when hovered while focused. Filled unless asked otherwise; Ghost for a field in a list row or inline text; Outline or Underline where an explicit line is wanted. A focus draws the field's edge in the theme's FieldFocus tone, neutral (color-mix(in srgb, var(--ui-color-on-surface) 28%, var(--ui-color-mark))) by default; SetShowFocusEdge(false) leaves it out for a field its container and its caret already frame — a composer that is a bubble's whole content
Buttons and badges Variant (UIButtonVariant) on a button, Variant (UIBadgeVariant) and Fill (UIBadgeFill) on a badge Buttons: Primary, Accent, Danger, Outline, Ghost, Link, Surface. Badges: Primary, Accent, Info, Warning, Success, Danger, Surface, Plain; filled as Filled, Tinted or Outline — unset, a variant fills and a colour tints
How much room a button takes Size (UISize) Small — inside a row, a toolbar, a list; Medium — a button standing on its own; Large — a call to action

Surface is for things that are a surface — a card, an expander, a dialog. A layout panel draws nothing by default and takes an arbitrary Background colour instead where a page genuinely wants one there. What stands on a surface steps off that surface, not off the page: a Filled field in a Surface card or a dialog mixes its fill into the card's or the dialog's, and a popup — a list, a picker, a menu, a tooltip — opened from inside a Surface panel or a dialog is lifted one step above it (--ui-color-surface with 8 % more of the text colour — on such a surface with a colour of its own too, since the popup's entries keep the page's ink). A Background or Tinted surface is the page's level again, and a popup opened there is the page's. A colour a person picked through a colour input is not judged as a theme role: what reads on top of it is decided by UIColorContrast.IsLightOverWhite — the colour laid over white, so its opacity counts — not by the ambient theme.

Selection

ISelectionStyleComponent.SelectionStyle (UISelectionStyle?) says what a chosen row or item looks like, on ItemsViewComponent, TableComponent, TreeComponent, ButtonGroupComponent, MenuComponent, TabsComponent and TabsViewComponent. UISelectionStyle carries Background, Foreground, Mark (UISelectionMark), MarkColor, Bold and ActionBarBackground (the ground of the row an action bar stands over; unset the pointer's wash, Transparent none) — any part left unset keeps the control's own default. UISelectionStyle.Ground(background) marks a choice by its fill alone; UISelectionStyle.Marked(mark, markColor) marks it with a line on one edge instead.

Theme mode

UIThemeMode is Light or Dark — no System member; null means "inherit" on a component and "follow the platform" on a session.

A component subtree can be forced into one mode regardless of the session's: IVisualComponent.Theme (UIThemeMode?), on every visual component, null by default to inherit the ambient theme.

For the whole session, the simplest route from a controller is to return SetThemeEffect (below): it repaints the open page at once and stores the mode in the session, so the next page load agrees.

[UICommand]
public UICommandResult UseDarkTheme()
    => UICommandResult.Ok([new SetThemeEffect(UIThemeMode.Dark)]);

Context.UpdateSessionAsync(session => session with { ThemeMode = UIThemeMode.Dark }, cancellationToken) stores the mode and switches the page before it returns, as the language does; either way, every other page open under the session switches too.

UIControllerBase.OnThemeChangedAsync(previousMode, cancellationToken) runs once per change, wherever it was made — the switcher, a SetThemeEffect, an update — as OnLanguageChangedAsync does (localization). It is the place to keep the mode on the reader's account; the way back is the sign-in command writing the account's mode into the session beside its language.

ThemeSwitcherComponent is the built-in control for a person to flip it themselves — a button that renders both glyphs (LightIcon, DarkIcon, sized by IconSize) and lets the stylesheet pick which one shows, since the page's shell markup is cached across themes; the switch itself runs entirely on the client. SetThemeEffect(UIThemeMode? mode) is the effect behind it, and has a server side: besides putting the client into the theme, it reports back to the session (WebUIHub.SetThemeAsync) so the next render agrees — a theme is a session setting, not just a client update, and Mode = null follows the platform's preference again. A switch the server pushes for a session that already holds the mode is marked so, and is not reported back.

As a settings form's field. AsField() draws the same switcher as a select-shaped field: a caption ("Theme", or SetTitle's words or key, decided at render), a box in the form's appearance (SetFieldVariant, Filled unless set) and a list of Light, Dark and System. System is SetThemeEffect(null): the session forgets its theme and the page follows the platform's prefers-color-scheme, as it changes. The field shows the theme the page is set to, whoever set it — another page of the session, a command, the header's button — and the page marks it, as the body is parsed and on every switch: the server never draws it, for the shell is cached outside the theme. UIForm.Field puts a note under it as under any field. The button stays a one-press flip between light and dark; from System it flips to the opposite of what the platform paints.

UIForm.Row(
    UIForm.Field(new ThemeSwitcherComponent().AsField(), "System follows the device."),
    UIForm.Field(new LanguageSwitcherComponent().AsField(), "The page is rewritten in place.")
)

A reader's own colours

A reader may keep a primary and an accent of their own over the application's palette, on the session beside the theme mode. UIThemeColors holds them — LightPrimary, LightAccent, DarkPrimary, DarkAccent, each a ColorVariant and each left unset meaning the application's; UIThemeColors.Create(primary, accent) gives both themes the same — and SetThemeColorsEffect applies them, from a command or an interaction:

[UICommand]
public UICommandResult ApplyColours()
    => UICommandResult.Ok([new SetThemeColorsEffect(UIThemeColors.Create(new ColorVariant(ColorName.NovaPurple)))]);

[UICommand]
public UICommandResult ResetColours()
    => UICommandResult.Ok([new SetThemeColorsEffect()]);

The page hands the colours to its session (UserSessionState.ThemeColors) and draws the stylesheet the server derives from them; every other page of the session switches with it, and every page the session renders from then on carries the same block after the theme's cached stylesheet. What stands on a colour, writes in it or shares its hue follows by one rule, UIColorPalette.WithPrimary/WithAccent: the colour's On* stays where it reads 4.5:1, else it becomes whichever of the page's ground and ink reads better, moved on until it reads; its ink is the colour moved toward the page's text until it reads 4.5:1 on the page; the selection and the focus ring, where drawn from the old hue, follow the new one. The same rule serves an application that changes its own palette's primary. Context.UpdateSessionAsync(s => s with { ThemeColors = … }) does the same from a command. A session store that keeps a session field by field keeps the colours as one JSON text; one that keeps none reads as the application's palette.