| name | blazor-ui-conventions |
| description | Apply Blazor and MudBlazor v9 conventions for render modes, dialogs, HAL-driven actions, theming, and component communication. |
| type | pattern |
| enforcement | suggest |
| priority | high |
Purpose
Use this skill when editing Razor components, Blazor client code, dialogs, render-mode interactions, or shared UI wrappers. It keeps the client aligned with MudBlazor v9, HAL affordances, and the design-token system.
When to Load
- Keywords: Blazor, Razor, MudBlazor, render mode, dialog, state, theme, wrapper component, HAL link.
- File patterns:
**/*.razor, **/*.razor.cs, Explore.Blazor.Client/**/*.cs, Explore.Blazor/**/*.cs.
- Intent IDs:
blazor-component-affordance, add-hal-link.
When NOT to Load
Must-Read Docs
Top 5 Invariants
- The default render mode is
InteractiveAuto, so HttpContext must not be used in InteractiveAuto or WASM execution paths.
- MudBlazor v9 APIs are required, including
ShowAsync<T>(), ShowMessageBoxAsync, CloseAsync, <CustomContent> for MudFileUpload, unified Palette, and IConverter<TInput,TOutput>.
- HAL
_links is the single source of truth for action affordances, so edit or delete buttons are gated by link presence rather than role or claim inspection.
- Child-to-parent communication uses
[Parameter] and EventCallback, and immutable Range<T> or DateRange values are replaced rather than mutated.
- Theming flows through the three-tier token system and shared wrappers in
Explore.Blazor.Client/Components/Common/ instead of ad hoc component styling.
Top 5 Anti-Patterns
- Using
HttpContext in InteractiveAuto or WASM code paths causes runtime failures when the component executes outside the server request pipeline.
- Gating UI action buttons with roles or claims instead of HAL
_links drifts from the API authorization contract.
- Using removed MudBlazor v8 APIs such as
Show<T>(), ShowMessageBox, or <ActivatorContent> in file uploads causes v9 migration breakage.
- Calling the API directly from Blazor components instead of going through the BFF bypasses the security and tenancy boundary.
- Using heavy shadows or
Elevation > 2 for ordinary content cards fights the project visual system and makes wrappers inconsistent.
Minimal Examples
@if (EventDto.HasHalLink("edit"))
{
<AppButton Variant="Variant.Filled" OnClick="OpenEditDialogAsync">
Edit
</AppButton>
}
@code {
[Parameter] public EventListItemDto EventDto { get; set; } = default!;
private Task OpenEditDialogAsync() => Task.CompletedTask;
}
public sealed class EventActions(IDialogService dialogService)
{
public async Task OpenAsync(Guid eventId)
{
var parameters = new DialogParameters<EditEventDialog>
{
{ x => x.EventId, eventId }
};
IDialogReference dialog = await dialogService.ShowAsync<EditEventDialog>(
"Edit event",
parameters);
await dialog.Result;
}
}
Verification Hooks
dotnet test --project Event.Architecture.Tests/Event.Architecture.Tests.csproj --configuration Release --verbosity quiet --filter FullyQualifiedName~Event.Architecture.Tests.BlazorClientArchitectureTestsdotnet test --project Explore.Blazor.Client.Tests/Explore.Blazor.Client.Tests.csproj --configuration Release --verbosity quietdotnet test --project Explore.Blazor.IntegrationTests/Explore.Blazor.IntegrationTests.csproj --configuration Release --verbosity quiet
Related Skills
