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.