TheNerdCollective.MudComponents.DesignTokens 2.1.0

TheNerdCollective.MudComponents.DesignTokens

Customer-specific CSS design tokens for MudBlazor 9.6. Define meaningful colors such as sand, forest, sun, and sea, then use the generated classes directly on any MudBlazor component. No wrappers, JavaScript, or MudBlazor fork is required.

See docs/DESIGN-TOKENS.md for architecture, design principles, and the brand-token model.

Brand packs (recommended)

Predefined brands ship as separate NuGet packages. Production apps install one brand only.

using TheNerdCollective.Brand.Dnf;

builder.Services.AddNerdDnfBrand();

See docs/BRAND-PACKAGES.md for dependency diagram and multi-brand demo setup.

Setup (manual tokens)

builder.Services.AddNerdDesignTokens(options =>
{
    options.Prefix = "dnf";
    options.Add("sand", new NerdColorToken
    {
        Value = "#E8D8AD",
        ContrastText = "#2D2D2D",
        Hover = "#D8C58E"
    });
    options.Add("forest", new NerdColorToken
    {
        Value = "#365C3A",
        Light = "#4D7A50",
        Dark = "#203B25",
        Hover = "#2D4D30",
        Surface = "#F0F7F0",
        Content = "#19301D",
        Interactive = "#2D4D30"
    });
});

Add the style component once, after MudThemeProvider:

<MudThemeProvider />
<NerdDesignTokenStyles />

Use the customer vocabulary in markup:

<MudGrid Class="dnf-forest">
    <MudText Class="dnf-sand">Nature first</MudText>
    <MudButton Class="dnf-forest">Read more</MudButton>
</MudGrid>

The generator maps all 80 MudBlazor 9.6 --mud-palette-* variables per token, so every component that reads the theme palette inherits the token color. Pattern-based selectors cover filled, outlined, and text variants for buttons, chips, alerts, FABs, avatars, badges, and progress indicators. Inputs (text fields, selects, checkboxes, radios, switches, sliders, ratings), navigation (tabs, nav links, breadcrumbs, menus), and structural components (tables, data grids, cards, dialogs, drawers, app bars) are included. Descendant selectors allow applying a token on a container such as MudGrid and styling all nested MudBlazor components. Hover, focus, active, checked, selected, and disabled states are covered.

Token names must be lowercase CSS identifiers, such as sand, forest-dark, or sea-2. Each application can define a different set of tokens and a different prefix.

ContrastText is optional for hex colors and is calculated automatically when omitted. Light and Dark provide mode-specific values; dark values are activated below an ancestor with data-theme="dark". Surface, Content, and Interactive are semantic roles that can be consumed by application CSS without changing the token's component selectors.

The generated selectors are intentionally versioned against MudBlazor 9.6. The package emits both MudBlazor palette variables and explicit selectors for component variants and states, so updates to MudBlazor can be checked with the CSS snapshot tests before changing the package dependency.

Design-system extras

options.Alias("primary-action", "forest");
options.AddRadius("card", "12px");
options.AddShadow("elevated", "0 4px 16px rgba(0,0,0,.16)");

This produces dnf-primary-action, dnf-radius-card, and dnf-shadow-elevated. MudBlazor CSS is isolated in @layer nerd-design-tokens; this does not import or mix Bootstrap or Tailwind styles.

For static hosting, generate a CSS artifact at build time:

NerdDesignTokenTools.WriteCss(options, "wwwroot/css/dnf-tokens.css");

Tokens can be exported with NerdDesignTokenTools.ExportJson(options), and NerdDesignTokenTools.CheckAccessibility(options) reports WCAG AA contrast failures.

CSS layers and scopes

CSS layers are opt-in because unlayered application CSS and MudBlazor CSS can otherwise have different cascade precedence:

options.UseCssLayer = true;
options.CssLayerName = "dnf-tokens";
options.ScopeSelector = "[data-brand='dnf']";

The package never imports Bootstrap or Tailwind. The layer only groups this package's generated MudBlazor overrides. Scopes generate selectors such as [data-brand='dnf'] .dnf-forest.

Google Stitch

Tokens can be exported to a portable Stitch DESIGN.md handoff:

File.WriteAllText(
    "DESIGN.md",
    NerdDesignTokenTools.ExportStitchDesignMd(options));

Google Stitch's open DESIGN.md format can then be imported into Stitch or converted with Google's tooling, for example:

npx @google/design.md export --format dtcg DESIGN.md > tokens.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

The generated DTCG/Tailwind files can be reviewed alongside the generated MudBlazor CSS, keeping the customer's design source portable across tools.

Visual catalog

Install the optional catalog package and register routes for /nerd-design-tokens:

<PackageReference Include="TheNerdCollective.MudComponents.DesignTokens.Catalog" />

builder.Services.AddNerdDesignTokens(options =>
{
    options.Prefix = "dnf";
    options.EnableCatalogPage = true; // default
    options.CatalogRoute = "/nerd-design-tokens";
});
builder.Services.AddNerdDesignTokenCatalog();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddNerdDesignTokenCatalog(app.Services)
    .AddNerdDesignSystemHub(app.Services);

AddNerdDesignTokenCatalog(app.Services) registers the catalog assembly when EnableCatalogPage is true. The default route is /nerd-design-tokens.

The catalog shows color swatches, light/dark preview, WCAG 2.1 AA/AAA badges with contrast ratios, live MudBlazor component previews, aliases, radius, and shadow tokens. Failing tokens are highlighted with warning banners and recommended foreground colors.

Startup warnings are logged when tokens fail WCAG AA:

options.WarnOnAccessibilityFailuresAtStartup = true;
options.WcagVersion = "2.1";

To use a custom route, create a host page and render the shared catalog component (the built-in default page is at /nerd-design-tokens):

@page "/kunde/design-tokens"
@rendermode InteractiveServer
<NerdDesignTokensCatalog />

Set options.CatalogRoute to match your route so hub links stay correct.