Styling Guide

BaristaNotes .NET MAUI Styling Guide

Overview

Use this skill when implementing or modifying visual elements in BaristaNotes. It provides the definitive color palette, typography, spacing system, theme keys, and coding patterns for consistent UI.

Keywords: MAUI styling, MauiReactor themes, coffee app colors, dark mode, light mode, AppColors, ThemeKeys, spacing, typography, visual design

Extension Philosophy

When implementing new UI features:

Prefer Reuse Over Creation

1. Search existing resources first - Check AppColors, ThemeKeys, AppIcons, and MaterialSymbolsFont before creating anything new
2. Use the closest existing option - If an 80% match exists, use it rather than creating a 100% match
3. Extend only when necessary - Add new tokens only when existing ones genuinely don't fit the use case

When Adding New Resources

• Colors: Must complement the existing coffee palette (warm browns, cream tones). Never override semantic colors (Primary, Success, Error, etc.)
• Theme Keys: Follow naming conventions in ThemeKeys.cs. Reuse existing styling patterns from ApplicationTheme.cs
• Icons: Search MaterialSymbolsFont.cs (3,700+ icons) before requesting new assets. Add to AppIcons.cs only if the icon will be reused across multiple components
• Spacing/Typography: Use existing AppSpacing and AppFontSizes tokens. These scales are intentionally limited for consistency

Color Palette

All colors are defined in AppColors.cs. Use theme-aware colors via AppColors.Light.* or AppColors.Dark.*.

Semantic Colors (Same in Both Themes)

Light Mode Coffee Palette

Dark Mode Coffee Palette

Using Colors in Code

// ✅ CORRECT: Theme-aware colors
.BackgroundColor(AppColors.Light.Surface)  // or AppColors.Dark.Surface
.TextColor(AppColors.Dark.TextPrimary)

// ✅ CORRECT: With theme check
var bgColor = ApplicationTheme.IsLightTheme ? AppColors.Light.Surface : AppColors.Dark.Surface;

// ❌ WRONG: Hardcoded hex values
.BackgroundColor(Color.FromArgb("#48362E"))  // Use AppColors instead

Typography

Font Families

Font Sizes (AppFontSizes)

Typography in Code

// Use constants from AppFontSizes
Label()
    .FontFamily("Manrope")
    .FontSize(AppFontSizes.TitleMedium)
    .TextColor(AppColors.Dark.TextPrimary)

// For headlines
Label()
    .FontFamily("ManropeSemibold")
    .FontSize(AppFontSizes.TitleLarge)

Spacing System (AppSpacing)

Spacing in Code

// ✅ CORRECT: Use AppSpacing constants
.Padding(AppSpacing.M)
.Margin(AppSpacing.S, AppSpacing.M)
VStack(spacing: AppSpacing.S)

// ❌ WRONG: Magic numbers
.Padding(16)  // Use AppSpacing.M instead

Theme Keys

Use ThemeKeys constants with .ThemeKey() for consistent, themed components.

Label Theme Keys

Border Theme Keys

Button Theme Keys

Using Theme Keys

// ✅ CORRECT: Apply theme keys for consistent styling
Label("Welcome")
    .ThemeKey(ThemeKeys.Headline)

Border(
    // content
)
    .ThemeKey(ThemeKeys.Card)

Button("Save")
    .ThemeKey(ThemeKeys.PrimaryButton)

Entry()
    .ThemeKey(ThemeKeys.Entry)

Icons

Icon Fonts

• Material Symbols: Use MaterialSymbolsFont.* constants from Fonts namespace
• Coffee Icons: Use font family "coffee-icons" with glyph codes

Common Icons (AppIcons)

// Pre-configured FontImageSource instances
AppIcons.CoffeeCup      // Coffee cup icon (NOT ☕ emoji!)
AppIcons.Feed           // Activity feed
AppIcons.Settings       // Settings gear
AppIcons.Edit           // Edit pencil
AppIcons.Delete         // Delete trash
AppIcons.Add            // Add plus
AppIcons.Ai             // AI/magic wand
AppIcons.Filter         // Filter list
AppIcons.FilterActive   // Active filter (primary color)

// Rating icons (0-4 scale) - NEVER use emoji!
AppIcons.GetRatingIcon(rating)  // Returns MaterialSymbolsFont sentiment icon
// 0 = Sentiment_very_dissatisfied (Terrible)
// 1 = Sentiment_dissatisfied (Bad)
// 2 = Sentiment_neutral (Average)
// 3 = Sentiment_satisfied (Good)
// 4 = Sentiment_very_satisfied (Excellent)

Icon Usage

// Using AppIcons
ImageButton()
    .Source(AppIcons.Edit)

// Using MaterialSymbolsFont directly
Label()
    .FontFamily(MaterialSymbolsFont.FontFamily)
    .Text(MaterialSymbolsFont.Coffee)
    .FontSize(24)

MANDATORY UI Guidelines

🚫 NO EMOJIS (NON-NEGOTIABLE)

Emojis are ABSOLUTELY PROHIBITED in all user interface code. This includes but is not limited to: ☕, ⭐, ⚠️, ✓, ✕, ℹ️, and ANY Unicode emoji character.

// ❌ ABSOLUTELY FORBIDDEN - Never use emojis
Label("☕ Coffee")           // BANNED
Label("⭐ Rating: 4")        // BANNED
Label("⚠️ Warning")          // BANNED

// ✅ CORRECT: Use MaterialSymbolsFont icons
Label()
    .FontFamily(MaterialSymbolsFont.FontFamily)
    .Text(MaterialSymbolsFont.Coffee)

Label()
    .FontFamily(MaterialSymbolsFont.FontFamily)
    .Text(MaterialSymbolsFont.Warning)

Why: Emojis render inconsistently across platforms, break accessibility (screen readers), and violate professional UI standards.

ThemeKey System (MANDATORY)

Never use inline styling methods. All styling MUST use the ThemeKey system for consistency and theme support.

// ❌ WRONG: Inline styling is PROHIBITED
Label("Title")
    .FontSize(24)
    .TextColor(Colors.Brown)
    .FontAttributes(FontAttributes.Bold)

// ✅ CORRECT: Always use ThemeKeys
Label("Title")
    .ThemeKey(ThemeKeys.Headline)

Before creating new theme keys, check existing keys in:

• ThemeKeys.cs - Theme key constants
• ApplicationTheme.cs - Theme implementations

Accessibility (WCAG 2.1 Level AA)

• All interactive elements must be keyboard navigable
• Screen-reader compatible labels required
• Minimum contrast ratios must be maintained
• Touch targets minimum 44x44dp

Deprecated APIs - DO NOT USE

// ❌ NEVER use these deprecated controls:
Frame()      // Use Border() instead
ListView()   // Use CollectionView() instead
TableView()  // Use CollectionView() instead

Rounded Corners - Use Border, NOT BoxView

// ❌ WRONG: BoxView corner radius distorts on rotation
BoxView()
    .BackgroundColor(backgroundColor)
    .CornerRadius(25)

// ✅ CORRECT: Border with RoundRectangle
Border()
    .BackgroundColor(backgroundColor)
    .StrokeThickness(0)
    .StrokeShape(new RoundRectangle { CornerRadius = 25 })

Minimum Touch Targets

Always ensure interactive elements have minimum 44x44dp touch targets:

Button()
    .MinimumHeightRequest(44)
    .MinimumWidthRequest(44)

Component Patterns

Card Component

Border(
    VStack(spacing: AppSpacing.S,
        Label(title).ThemeKey(ThemeKeys.CardTitle),
        Label(subtitle).ThemeKey(ThemeKeys.CardSubtitle)
    )
)
    .ThemeKey(ThemeKeys.Card)

Form Input

VStack(spacing: AppSpacing.XS,
    Label("Label").ThemeKey(ThemeKeys.FormLabel),
    Border(
        Entry()
            .Placeholder("Enter value")
            .ThemeKey(ThemeKeys.Entry)
    )
        .ThemeKey(ThemeKeys.InputBorder)
)

Primary Action Button

Button("Save")
    .ThemeKey(ThemeKeys.PrimaryButton)
    .OnClicked(HandleSave)

Danger/Delete Button

Button("Delete")
    .ThemeKey(ThemeKeys.DangerButton)
    .OnClicked(HandleDelete)

Orientation Handling

When UI elements need to respond to orientation changes:

private class State
{
    public DisplayOrientation Orientation { get; set; } = DisplayOrientation.Portrait;
}

protected override void OnMounted()
{
    DeviceDisplay.MainDisplayInfoChanged += OnDisplayInfoChanged;
    SetState(s => s.Orientation = DeviceDisplay.MainDisplayInfo.Orientation);
    base.OnMounted();
}

protected override void OnWillUnmount()
{
    DeviceDisplay.MainDisplayInfoChanged -= OnDisplayInfoChanged;
    base.OnWillUnmount();
}

private void OnDisplayInfoChanged(object? sender, DisplayInfoChangedEventArgs e)
{
    SetState(s => s.Orientation = e.DisplayInfo.Orientation);
}

File References