Foundations
Layout System
Two-layer architecture for app layouts: SilliumLayoutBase handles infrastructure (theme, culture, providers), Shell components provide configurable visual structure (AppBar, Sidebar, Footer).
Overview
The layout system separates infrastructure plumbing from visual structure. Instead of every layout manually wiring ThemeProvider, SnackbarProvider, culture management and dev tools, the system provides reusable building blocks at three layers.
| Layer | Type | Responsibility |
|---|---|---|
| SilliumLayoutBase | C# class | Optional base class for layouts. Provides culture management (ApplyCurrentCulture, CultureChanged events, ContentRenderKey) and virtual properties for theme/snackbar configuration. |
| LayoutShell | Razor component | Infrastructure wrapper component. Renders ThemeProvider, Culture CascadingValue, SnackbarProvider, GlobalLoaderProvider, and Dev Tools (if registered). |
| Shell Components | Razor components | Configurable visual structure components: SidebarShell (dashboard/admin), MinimalShell (login/error), TopNavShell (marketing/public). Pure layout, no infrastructure logic. |
Architecture
A consumer layout inherits SilliumLayoutBase, wraps content in LayoutShell for infrastructure, and uses a Shell component for visual structure. The three layers compose cleanly without duplication.
@@inherits SilliumLayoutBase ← Culture management, ContentRenderKey
<LayoutShell> ← ThemeProvider, Providers, DevTools
<SidebarShell> ← Visual structure (AppBar + Sidebar + Footer)
<AppBarStartContent>...</AppBarStartContent>
<AppBarEndContent>...</AppBarEndContent>
<SidebarContent>...</SidebarContent>
<ChildContent>@@Body</ChildContent>
<FooterContent>...</FooterContent>
</SidebarShell>
</LayoutShell>Composition over inheritance
Shell components are regular Blazor components (inherit SilliumComponentBase), not layout base classes. They can be mixed, swapped, or nested without affecting infrastructure wiring.SilliumLayoutBase
Abstract base class inheriting LayoutComponentBase. Handles culture lifecycle automatically: subscribes to CultureChanged, applies CurrentCulture before each render, provides ContentRenderKey for culture-triggered re-renders, and cleans up on Dispose.
| Member | Type | Description |
|---|---|---|
| CultureService | ICultureService | Injected culture service. Access current culture, supported cultures, and trigger culture changes. |
| ContentRenderKey | string | Returns current culture name. Use as @@key to force re-render on culture change. |
| DefaultThemeMode | ThemeMode | Virtual property. Override to change the default theme mode (Auto, Light, Dark). Default: Auto. |
| ThemeStorageKey | string | Virtual property. Override to change the localStorage key for theme persistence. Default: "sillium-theme". |
| SnackbarPosition | SnackbarPosition | Virtual property. Override to change snackbar position. Default: BottomRight. |
LayoutShell
Wrapper component that handles all infrastructure rendering. Wrap your Shell component inside LayoutShell to get ThemeProvider, culture cascading, snackbar/loader providers, and dev tools automatically.
LayoutShell renders: ┌─────────────────────────────────────────┐ │ <ThemeProvider> │ │ <CascadingValue Name="Culture"> │ │ <div @@key="ContentRenderKey"> │ │ @@ChildContent ← your shell here │ │ </div> │ │ </CascadingValue> │ │ <SnackbarProvider /> │ │ <GlobalLoaderProvider /> │ │ <DesignDevTools /> (if registered)│ │ <TranslationDevTools />(if registered)│ │ </ThemeProvider> │ └─────────────────────────────────────────┘
Dev Tools are conditional
DesignDevTools and TranslationDevTools are only rendered if their services are registered via AddSilliumDesignDevTools() and AddSilliumDevTranslationTools(). No performance overhead in production.Shell Components
Three pre-built shell components cover common layout patterns. Each provides configurable parameters and RenderFragment slots for content areas. All respect the layout-shell CSS class for theme-controlled max-width.
SidebarShell
Full-featured layout with AppBar, collapsible Sidebar, main content area, and optional Footer. On mobile (<1024px), the sidebar becomes a Drawer with hamburger button. Ideal for dashboards and admin panels.
| Parameter | Type | Default | Description |
|---|---|---|---|
| AppBarHeight | int | 64 | Height of the AppBar in pixels. |
| AppBarSticky | bool | true | Whether the AppBar stays fixed at the top when scrolling. |
| AppBarTransparent | bool | false | Removes background and border from the AppBar. |
| SidebarWidth | int | 280 | Width of the sidebar in pixels. |
| SidebarPosition | SidebarPosition | Left | Place the sidebar on the left or right side. |
| FooterSticky | bool | false | Whether the footer stays fixed at the bottom. |
| ContentMaxWidth | string? | null | Tailwind max-width class for the content area (e.g. "max-w-5xl"). |
MinimalShell
Minimal full-screen layout with optional transparent action bar (top-right). No sidebar, no navigation. Ideal for login pages, error pages, and landing pages.
| Parameter | Type | Default | Description |
|---|---|---|---|
| CenterContent | bool | false | Center content both horizontally and vertically. |
| ContentMaxWidth | string? | null | Tailwind max-width class for the content area (e.g. "max-w-md"). |
| BackgroundClass | string? | null | Custom CSS class for the background (e.g. gradient). Default: bg-app-bg. |
TopNavShell
Top navigation layout with AppBar, full-width content, and optional Footer. No sidebar. Supports transparent AppBar for hero sections. Ideal for marketing sites and public pages.
| Parameter | Type | Default | Description |
|---|---|---|---|
| AppBarHeight | int | 64 | Height of the AppBar in pixels. |
| AppBarSticky | bool | true | Whether the AppBar stays fixed at the top when scrolling. |
| AppBarTransparent | bool | false | AppBar overlays content with no background. Use for hero sections. |
Usage Example
A typical consumer layout inherits SilliumLayoutBase, wraps in LayoutShell, and uses SidebarShell for visual structure. The consumer only writes the app-specific parts: logo, navigation, and footer content.
// MainLayout.razor
@@inherits SilliumLayoutBase
<LayoutShell>
<SidebarShell AppBarHeight="64"
SidebarWidth="280"
FooterSticky="true">
<AppBarStartContent>
<a href="/"><Icon Name="home" /> My App</a>
</AppBarStartContent>
<AppBarEndContent>
<LanguageChooser />
<ThemeToggle />
</AppBarEndContent>
<SidebarContent>
<NavMenu />
</SidebarContent>
<ChildContent>
@@Body
</ChildContent>
<FooterContent>
© 2026 My Company
</FooterContent>
</SidebarShell>
</LayoutShell>What you no longer need to write
ThemeProvider wrapping, CultureInfo management, SnackbarProvider, GlobalLoaderProvider, Dev Tools registration, CultureChanged event handling, ContentRenderKey management, and Dispose cleanup are all handled automatically.File Reference
All layout system files in Sillium.Core.Components.
| File | Responsibility |
|---|---|
| SilliumLayoutBase.cs | Base class: culture lifecycle, ContentRenderKey, virtual theme/snackbar config. |
| Shells/LayoutShell.razor | Infrastructure wrapper: ThemeProvider, CascadingValue, Providers, Dev Tools. |
| Shells/SidebarShell.razor | Visual shell: AppBar + Sidebar (Drawer on mobile) + Content + Footer. |
| Shells/MinimalShell.razor | Visual shell: Full-screen with optional transparent action bar. For login/error pages. |
| Shells/TopNavShell.razor | Visual shell: Top navigation + Content + Footer. For marketing/public pages. |