# Theme and Surface Materials

Nexamas UI treats theme selection and surface material selection as Application-owned visual policy. Consumers select registered themes/materials through public facades; they do not mutate internal theme catalogs or visual registries.

## Theme selection

Application-level theme selection:

```vbnet
Dim app = MASApplication.Create()
Dim themes = app.Theme.GetAll()

For Each theme In themes
    Console.WriteLine(theme.Id & " - " & theme.DisplayName)
Next

app.Theme.Use("signature-dark")
```

Window-facing selection and refresh:

```vbnet
If window.Theme.TryUse("signature-dark") Then
    window.Theme.Refresh()
End If
```

Theme selection is global for the process. The window facade refreshes the current window after applying the shared theme.

## Surface materials

Use the public surface-material gateway/scope documented by the Theme/Surface pages. A typical usage shape is:

```vbnet
Dim materials = MASApplicationSurfaceMaterialGateway.GetSelectableMaterials()

Using scope = MASApplicationSurfaceMaterialGateway.CreateScope(window)
    scope.Apply("glass")
End Using
```

If a material key is not available in the current version, keep the application on the default material and do not fabricate a local renderer.

## Safe mental model

| Layer | Consumer responsibility |
|---|---|
| Theme | Select an existing registered theme by id |
| Window refresh | Ask the window theme facade to refresh after changes |
| Surface material | Select available material keys through the public gateway |
| Custom renderer | Not part of the public v1 consumer path |

## Do not expose

Do not document or consume `ThemeManager`, `ThemeHost`, Theme Studio internals, material registries, painter classes, or visual audit report classes as public application APIs.

## Related pages

- [Theme and surfaces guide](../developer/theme-and-surfaces.md)
- [Theme/surface reference](../reference/theme-surface-surface.md)
- [Theme/surface product page](../product/theme-surface-system.md)

## Evidence

- `MASSystem/Application/Facade/MASApplicationTheme.vb`
- `MASSystem/Application/Facade/MASApplicationWindowTheme.vb`
- `MASSystem/Application/Facade/SurfaceMaterials/MASApplicationSurfaceMaterialGateway.vb`
- `MASSystem/Application/Facade/SurfaceMaterials/MASApplicationSurfaceMaterialScope.vb`
- `MASSystem/Visual/ThemeSystem/`
- `MASSystem/Visual/Surface/`