AppSurface Search
Section API Reference
API Reference Language: C# Component: Theming Audience: developer

Theming

Type

AppSurfaceThemeServiceCollectionExtensions

Source

Registers immutable AppSurface theme-pair services for a host.

Method

AddAppSurfaceTheming

2 overloads
IServiceCollection AddAppSurfaceTheming(this IServiceCollection services, Action<AppSurfaceThemeRegistryOptions> configure)
Source

Validates and registers configured semantic pairs and their default resolver.

Parameters

  • services
    Service collection receiving the sealed registry.
  • configure
    Host configuration for pairs and the default mode.

Returns

The original services instance.

Exceptions

  • ArgumentNullException
    Thrown when an argument is null .
  • AppSurfaceThemeValidationException
    Thrown when configuration cannot safely produce a complete pair.
IServiceCollection AddAppSurfaceTheming(this IServiceCollection services, AppSurfaceThemeRegistryOptions options)
Source

Validates and registers an explicit semantic pair configuration snapshot.

Parameters

  • services
    Service collection receiving the sealed registry.
  • options
    Host configuration for pairs and the default mode.

Returns

The original services instance.

Exceptions

  • ArgumentNullException
    Thrown when an argument is null .
  • AppSurfaceThemeValidationException
    Thrown when configuration cannot safely produce a complete pair.
Method

AddRequiredThemeExtension

IServiceCollection AddRequiredThemeExtension<TSettings>(this IServiceCollection services)
Source

Requires an application-owned extension provider to cover every configured semantic pair.

Type parameters

  • TSettings
    Application-owned non-null settings type.

Parameters

  • services
    Service collection receiving the required-provider validator.

Returns

The original services instance.

Exceptions

  • ArgumentNullException
    Thrown when services is null .
  • AppSurfaceThemeValidationException
    Thrown when IAppSurfaceThemeRegistry is first resolved and the provider is missing (ASTHEME201) or supplies no non-null setting for a registered pair (ASTHEME202). This method itself does not throw it.

Remarks

Register IAppSurfaceThemeExtensionProvider{TSettings} before the neutral registry is first resolved. The provider remains application-owned: this method verifies only provider presence and one non-null setting for each registered pair. It neither validates, serializes, nor logs TSettings .

Type

AppSurfaceThemeId

Source

Identifies a registered semantic theme pair.

Property

Value

string Value { get; } Source

Gets the canonical identifier value.

Type

AppSurfaceThemeRoles

Source

Defines the minimum semantic color roles consumed by AppSurface-owned UI.

Property

Canvas

string Canvas { get; } Source

Gets the primary page canvas color.

Property

Surface

string Surface { get; } Source

Gets the default content-surface color.

Property

RaisedSurface

string RaisedSurface { get; } Source

Gets the raised content-surface color.

Property

Text

string Text { get; } Source

Gets the primary readable text color.

Property

MutedText

string MutedText { get; } Source

Gets the secondary readable text color.

Property

Border

string Border { get; } Source

Gets the visible border and divider color.

Property

Accent

string Accent { get; } Source

Gets the default accent color.

Property

AccentStrong

string AccentStrong { get; } Source

Gets the high-emphasis accent color.

Property

Danger

string Danger { get; } Source

Gets the error and destructive-action color.

Property

Focus

string Focus { get; } Source

Gets the keyboard-visible focus color.

Type

AppSurfaceThemePair

Source

Pairs complete light and dark semantic role sets under one identifier.

Method

AppSurface

AppSurfaceThemePair AppSurface()
Source

Creates AppSurface's built-in accessible semantic pair.

Returns

A new immutable pair instance named appsurface .

Method

Graphite

AppSurfaceThemePair Graphite()
Source

Creates the built-in Graphite semantic light/dark pair.

Returns

A new immutable pair instance named graphite .

Remarks

Graphite is a shared semantic pair for hosts that register AppSurface theming. It is distinct from the Docs-local fixed-dark GraphiteDark compatibility preset, which does not register a shared pair.

Property

Id

AppSurfaceThemeId Id { get; } Source

Gets the canonical pair identifier.

Property

Light

AppSurfaceThemeRoles Light { get; } Source

Gets the complete light role set.

Property

Dark

AppSurfaceThemeRoles Dark { get; } Source

Gets the complete dark role set.

Type

AppSurfaceThemeResolution

Source

Represents the sealed default pair together with its host-selected mode.

Property

Id

AppSurfaceThemeId Id { get; } Source

Gets the resolved pair identifier.

Property

Mode

AppSurfaceThemeMode Mode { get; } Source

Gets the host-selected rendering mode.

Property

Light

AppSurfaceThemeRoles Light { get; } Source

Gets the sealed light role set.

Property

Dark

AppSurfaceThemeRoles Dark { get; } Source

Gets the sealed dark role set.

Type

IAppSurfaceThemeExtensionProvider<TSettings>

Source

Allows an adapter to obtain application-owned settings for a registered pair.

Type parameters

  • TSettings
    Application-owned settings type. Neutral theming neither validates nor serializes it.
Method

TryGet

bool TryGet(AppSurfaceThemeId themeId, out TSettings settings)
Source

Attempts to get settings for the supplied sealed pair.

Parameters

  • themeId
    Registered theme-pair identifier.
  • settings
    Application-owned settings when available.

Returns

true when settings exist for themeId ; otherwise false .

Type

AppSurfaceThemeRegistryOptions

Source

Configures registered theme pairs and the host's default rendering mode.

Property

DefaultTheme

AppSurfaceThemeId DefaultTheme { get; set; } Source

Gets or sets the pair used by IAppSurfaceThemeResolver.ResolveDefault .

Property

DefaultMode

AppSurfaceThemeMode DefaultMode { get; set; } Source

Gets or sets the host's default browser rendering mode.

Property

Pairs

IList<AppSurfaceThemePair> Pairs { get; } Source

Gets the registered semantic light/dark pairs.

Type

IAppSurfaceThemeRegistry

Source

Looks up validated registered pairs by identifier.

Method

GetRequired

AppSurfaceThemePair GetRequired(AppSurfaceThemeId id)
Source

Gets a sealed pair by its canonical identifier.

Parameters

  • id
    Registered pair identifier.

Returns

The sealed semantic pair whose AppSurfaceThemePair.Id equals id .

Exceptions

  • KeyNotFoundException
    Thrown when id is not registered.
Property

ThemeIds

IReadOnlyCollection<AppSurfaceThemeId> ThemeIds { get; } Source

Gets the non-empty, ordinally unique canonical ids of every sealed registered pair in registration order.

Remarks

Each id returned by this collection must resolve through GetRequired to a pair whose AppSurfaceThemePair.Id equals that id. Consumers may reject implementations that do not maintain this sealed-snapshot contract.

Type

IAppSurfaceThemeResolver

Source

Resolves the host-selected default theme pair.

Method

ResolveDefault

AppSurfaceThemeResolution ResolveDefault()
Source

Resolves the sealed pair and rendering mode configured by the host.

Returns

The host's default semantic theme resolution.

Type

AppSurfaceThemeDiagnostic

Source

Provides a stable, safe theme configuration diagnostic.

Parameters

  • Code
    Stable ASTHEME diagnostic code.
  • Severity
    Safety impact of the condition.
  • Problem
    Safe one-line failure description.
  • Cause
    Safe explanation with applicable pair, role, or configuration path.
  • Fix
    Concrete remediation.
  • Documentation
    Canonical troubleshooting link.
Method

Create

AppSurfaceThemeDiagnostic Create(string code, string problem, string cause, string fix, AppSurfaceThemeDiagnosticSeverity severity = AppSurfaceThemeDiagnosticSeverity.Error)
Source

Creates a diagnostic linked to the canonical theme troubleshooting reference.

Parameters

  • code
    Stable diagnostic code.
  • problem
    Safe one-line failure description.
  • cause
    Safe explanation.
  • fix
    Concrete remediation.
  • severity
    Safety impact of the condition.

Returns

A stable diagnostic with its canonical documentation link.

Type

AppSurfaceThemeValidationException

Source

Thrown when a theme registry cannot produce a safe sealed snapshot.

Property

Diagnostics

IReadOnlyList<AppSurfaceThemeDiagnostic> Diagnostics { get; } Source

Gets all safe diagnostics that prevented registry creation.

Type

AppSurfaceThemeRegistry

Source

Validates and resolves immutable semantic theme pairs.

Method

GetRequired

AppSurfaceThemePair GetRequired(AppSurfaceThemeId id)
Source

Gets a sealed pair by its canonical identifier.

Parameters

  • id
    Registered pair identifier.

Returns

A defensive snapshot of the registered pair.

Exceptions

  • KeyNotFoundException
    Thrown when id is not registered.
Method

ResolveDefault

AppSurfaceThemeResolution ResolveDefault()
Source

Resolves the host-selected default pair and mode.

Returns

A defensive snapshot of the default resolution.

Method

Validate

IReadOnlyList<AppSurfaceThemeDiagnostic> Validate(AppSurfaceThemeRegistryOptions options)
Source

Validates a candidate registry configuration without creating a registry.

Parameters

  • options
    Candidate host configuration.

Returns

All stable diagnostics that prevent safe registry creation.

Method

IsSafeResolution

bool IsSafeResolution(AppSurfaceThemeResolution? resolution)
Source

Determines whether a sealed resolution can be safely consumed by a package-owned adapter.

Parameters

  • resolution
    The resolution to validate.

Returns

true when the resolution satisfies the neutral pair contract; otherwise false .

Remarks

This predicate is intended for adapters that need a fail-closed boundary without serializing a Web document. It applies the same identifier, mode, role, and contrast checks used for registry registration.

Enum

AppSurfaceThemeMode

Source

Identifies the host-selected rendering behavior for a semantic theme pair.

Enum

AppSurfaceThemeDiagnosticSeverity

Source

Classifies the safety impact of a theme diagnostic.