| name | design-system |
| description | CSS @layer architecture, 3-tier design tokens, and MudBlazor wrapper components. |
| type | domain |
| enforcement | enforce |
| priority | high |
ABOUTME: CSS design system skill covering @layer architecture, design tokens, and wrapper components.
ABOUTME: Enforces layer ordering, token usage, and MudBlazor wrapper patterns.
Design System
Keywords
css layers, @layer, design tokens, wrapper component, AppButton, AppCard, AppTextField, AppIconButton, AppDialogShell, DialogOptionsFactory, AppearanceStyleBuilder, mudblazor override, display contents, ::deep
File Patterns
wwwroot/css/layers.csswwwroot/css/tokens.csswwwroot/css/mudblazor-overrides.csswwwroot/css/utilities.css**/Components/Common/App*.razor**/Components/Common/App*.razor.css**/Helpers/AppearanceStyleBuilder.cs**/Services/DialogOptionsFactory.cs
Non-Inferable Rules
- CSS layers order (lowest→highest):
reset → base → tokens → mudblazor-overrides → components → utilities. Unlayered CSS (Blazor CSS isolation, MudThemeProvider) beats all layered — by design.
- MudBlazor
.mud-* overrides are ONLY allowed in mudblazor-overrides.css. Each override must have a comment justifying it. No bare .mud-* selectors anywhere else.
- All wrapper components use
display: contents to be transparent in layout, then ::deep to style MudBlazor internals via CSS isolation.
- Design tokens follow 3 tiers: Primitives (raw values), Semantic (contextual meaning from
--mud-palette-*), Component (scoped to specific components).
- Spacing uses a 4px grid:
--isl-space-1 (4px) through --isl-space-16 (64px).
- Typography is fluid: H1–H6 use
clamp() between 320px and 1280px viewport widths.
- DialogOptionsFactory provides 4 standard presets: Small, Medium, Confirmation, Editor. Always use a preset — never create
DialogOptions manually.
- AppearanceStyleBuilder has 4 background effects: None, SoftOverlay (0.24), StrongOverlay (0.40), Blur (0.18). Methods:
BuildStyle, BuildHeroStyle, BuildBannerStyle.
Activation
Load this skill when:
- Creating or modifying CSS files in
wwwroot/css/
- Working on wrapper components in
Components/Common/
- Implementing appearance/theming features
- Overriding MudBlazor styles
- Creating or modifying dialog options
Resources
resources/layer-architecture.md — 6 CSS layers, ordering rules, override policyresources/token-system.md — 3-tier token definitions, naming conventionsresources/wrapper-components.md — 5 wrappers, parameters, styling patternsresources/appearance-builder.md — AppearanceStyleBuilder, DialogOptionsFactory, effects
Related
docs/DESIGN_SYSTEM.md.agents/skills/blazor-ui-conventions/SKILL.md.agents/skills/blazor-css-isolation/SKILL.md
