Introduction

1. Overview

Marai.UI provides production-ready Blazor components with semantic variants, token-driven theming, dark mode support, and accessibility built in. Components are beautiful by default — write <MButton>Save Changes</MButton> and the result is already styled, accessible, and production-ready.

When you need to go further, you own every visual decision using Tailwind CSS utility classes through the Class parameter. User-supplied classes always win conflicts — safe, predictable, and visible to the Tailwind scanner.

Marai.UI targets .NET 10 and works with Blazor Server, Blazor WebAssembly, and Blazor Web App projects.

2. Design Philosophy

Beautiful by Default

Every component ships with production-grade styling driven by a semantic design token system. You can render a complete, polished UI without writing a single Tailwind class. Tokens handle colors, spacing, radius, and dark mode automatically.

<MButton>Save Changes</MButton>
<MBadge Variant="Variant.Success">Approved</MBadge>
<MCard>
    <MCardHeader>
        <MCardTitle>Settlement Summary</MCardTitle>
        <MCardDescription>Daily merchant settlement overview</MCardDescription>
    </MCardHeader>
</MCard>

Semantic Variants

Components use the Variant enum to communicate intent. Variants map directly to the token system — switch themes and every component updates automatically.

Token-Driven Theming

Marai.UI uses CSS custom properties for all component colors. The <MStyleInjector /> component writes a :root block containing the active theme's tokens. Switching themes at runtime is a single ThemeService call — no component re-renders, no class swaps.

Safe Tailwind Overrides

The Class parameter is always appended last, so user-supplied utilities win every conflict. Compose layouts, adjust spacing, change radius — anything — without worrying about specificity or !important hacks.

<MButton Variant="Variant.Primary" Class="rounded-full px-8">
    Approve Settlement
</MButton>

3. Composable Structure

Complex components expose named sub-components rather than a monolithic element. MCard gives you MCardHeader, MCardTitle, MCardDescription, MCardContent, and MCardFooter — each with its own Class parameter. Include only the parts you need.

<MCard>
    <MCardHeader>
        <MCardTitle>Transaction #4821</MCardTitle>
        <MCardDescription>Submitted 10 May 2026 · Pending review</MCardDescription>
    </MCardHeader>
    <MCardContent>
        <!-- content -->
    </MCardContent>
    <MCardFooter>
        <MButton Variant="Variant.Primary">Approve</MButton>
        <MButton Variant="Variant.Outline">Reject</MButton>
    </MCardFooter>
</MCard>

4. Accessibility Built In

Components manage ARIA attributes, keyboard navigation, focus trapping, and screen-reader announcements automatically. You do not need to add role, aria-expanded, aria-controls, or focus management manually — the components wire these based on state.

• Focus-visible rings are built into every interactive component
• MButton with Loading="true" sets aria-disabled and aria-busy
• MDialog traps focus and restores it on close
• MDropdown and MTabs respond to arrow-key navigation
• MTooltip wires role="tooltip" and aria-describedby automatically

5. MStyleInjector

Place <MStyleInjector /> in your root layout or App.razor. It renders the CSS token block that powers all component colors and dark mode. Without it, components still render but lose token-based colors and dark mode support.

<MStyleInjector />

Next Steps

• Installation & Setup — install the NuGet package and configure your project
• Theming — customize the design token system and enable dark mode
• Browse Components — explore the full component library with live examples
• Playground — experiment with components interactively