---
name: maui-branding-expert
description: Xây dựng hệ thống UI/UX chuẩn Enterprise cho .NET MAUI, bao gồm Resource Dictionary, Control Templates, Custom Handlers và Accessibility. Use for Design System, branding controls, hoặc khi cần standardized UI components.
compatibility: ".NET 9+ MAUI, CommunityToolkit.Maui 9+"
metadata:
  author: Velik Ho
  version: "1.0"
  references: "Microsoft .NET MAUI Documentation, Enterprise Application Patterns"
---

# .NET MAUI Branding Controls Workflow

Bạn là một chuyên gia về UI/UX và XAML trong .NET MAUI. Nhiệm vụ của bạn là hiện thực hóa Design System thành code có khả năng tái sử dụng cao (Reusability) và dễ bảo trì (Maintainability). **Tuyệt đối không hard-code màu sắc hay kích thước trực tiếp trong View.**

## When to Use This Skill / Khi Nào Sử Dụng

Use this skill when:
- Xây dựng Design System / UI Kit cho app
- Tạo custom branded controls (BrandButton, BrandEntry, CardView...)
- Thiết lập Resource Dictionary architecture
- Tùy chỉnh native controls với Handlers
- Đảm bảo Accessibility (WCAG) compliance

**DO NOT use when:**
- Simple prototyping / Làm prototype nhanh
- Single-use UI components / Component dùng 1 lần
- Blazor Hybrid apps (use CSS/Blazor patterns)

## Overview / Tổng Quan

```
┌──────────────────────────────────────────────────────────────────┐
│               WORKFLOW XÂY DỰNG BRANDING CONTROLS                │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────┐     ┌─────────────────┐                        │
│  │   PHASE 1   │────►│     PHASE 2     │                        │
│  │  RESOURCE   │     │   CONTROL       │                        │
│  │  DICTIONARY │     │  CUSTOMIZATION  │                        │
│  │ - Colors    │     │ - Styles (L1)   │                        │
│  │ - Typography│     │ - Templates(L2) │                        │
│  │ - Theme     │     │ - Handlers (L3) │                        │
│  └─────────────┘     └────────┬────────┘                        │
│                               │                                  │
│                               ▼                                  │
│  ┌─────────────┐     ┌─────────────────┐                        │
│  │   PHASE 4   │◄────│     PHASE 3     │                        │
│  │ ACCESSIBILITY│     │    HANDLER      │                        │
│  │             │     │  MODIFICATION   │                        │
│  │ - Semantic  │     │ - AppendMapping │                        │
│  │ - HeadingLv │     │ - PlatformView  │                        │
│  │ - FontScale │     │ - Partial Class │                        │
│  └─────────────┘     └─────────────────┘                        │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

---

## Phase 1: Resource Dictionary Architecture / Kiến Trúc Resource

**Goal**: Tổ chức tài nguyên UI để dễ dàng thay đổi thương hiệu (Re-branding).

**Detailed Guide**: [Resource Architecture](./guidelines/resource-architecture.md)

### Nguyên tắc cốt lõi

1. **Phân tách Resource** - Không gộp tất cả vào `App.xaml`
   ```
   Resources/Styles/
   ├── Colors.xaml      # Bảng màu (Color Palette)
   ├── Typography.xaml  # Font, FontSize, LineHeight
   └── Theme.xaml       # Styles cho controls
   ```

2. **Merged Dictionaries** - Gộp files theo thứ tự ưu tiên trong `App.xaml`

3. **AppThemeBinding** - Luôn định nghĩa màu cho cả Light/Dark Mode

### Quick Pattern

```xml
<!-- Colors.xaml -->
<Color x:Key="BrandPrimary">{AppThemeBinding 
    Light=#2196F3, Dark=#64B5F6}</Color>
<Color x:Key="BrandSurface">{AppThemeBinding 
    Light=#FFFFFF, Dark=#1E1E1E}</Color>
```

---

## Phase 2: Control Customization Strategy / Chiến Lược Tùy Biến

**Goal**: Tùy chỉnh controls theo thứ tự ưu tiên phù hợp.

**Detailed Guide**: [Handler Customization](./guidelines/handler-customization.md)

### Thứ tự ưu tiên

| Level | Method | Use When |
|-------|--------|----------|
| **L1** | XAML Styles + VSM | Thay đổi cơ bản (màu, bo góc, hover) |
| **L2** | ControlTemplate | Thay đổi cấu trúc visual hoàn toàn |
| **L3** | Handlers | Can thiệp Native API (bỏ underline, đổi cursor) |

### Level 1: XAML Styles

```xml
<Style TargetType="Button" x:Key="BrandButton">
    <Setter Property="BackgroundColor" 
            Value="{StaticResource BrandPrimary}" />
    <Setter Property="TextColor" Value="White" />
    <Setter Property="CornerRadius" Value="8" />
    <Setter Property="VisualStateManager.VisualStateGroups">
        <VisualStateGroupList>
            <VisualStateGroup x:Name="CommonStates">
                <VisualState x:Name="Normal" />
                <VisualState x:Name="Pressed">
                    <VisualState.Setters>
                        <Setter Property="Scale" Value="0.98" />
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateGroupList>
    </Setter>
</Style>
```

### Level 2: ControlTemplate

```xml
<ControlTemplate x:Key="CardTemplate">
    <Frame CornerRadius="12" 
           BackgroundColor="{StaticResource BrandSurface}"
           HasShadow="True">
        <ContentPresenter />
    </Frame>
</ControlTemplate>
```

### Level 3: Handlers (Advanced)

```csharp
// BẮT BUỘC: Sử dụng AppendToMapping, KHÔNG dùng Custom Renderer
EntryHandler.Mapper.AppendToMapping("BrandEntry", (handler, view) =>
{
#if ANDROID
    handler.PlatformView.SetBackgroundColor(Android.Graphics.Color.Transparent);
#elif IOS
    handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});
```

---

## Phase 3: Handler Modification / Sửa Đổi Handler

**Goal**: Can thiệp sâu vào Native View một cách an toàn.

**Detailed Guide**: [Handler Customization](./guidelines/handler-customization.md)

### Key Patterns

1. **AppendToMapping** - Thêm tùy chỉnh vào cuối chuỗi xử lý mặc định
2. **PrependToMapping** - Thêm vào đầu chuỗi (ít dùng)
3. **ModifyMapping** - Thay thế hoàn toàn (nguy hiểm, tránh dùng)

### Cross-Platform Partial Classes

Khi code native quá dài, tách thành Partial Classes:

```csharp
// Services/BrandingService.cs (shared)
public partial class BrandingService
{
    public partial void ConfigureEntry(IEntry entry);
}

// Platforms/Android/Services/BrandingService.cs
public partial class BrandingService
{
    public partial void ConfigureEntry(IEntry entry)
    {
        // Android-specific implementation
    }
}
```

---

## Phase 4: Accessibility (Enterprise Required) / Tính Năng Truy Cập

**Goal**: Tuân thủ chuẩn WCAG cho ứng dụng Enterprise.

**Detailed Guide**: [Accessibility Rules](./guidelines/accessibility-rules.md)

### Key Requirements

1. **SemanticProperties** - Thay thế AutomationProperties (đã cũ)
   ```xml
   <Button Text="Submit"
           SemanticProperties.Description="Submit form button"
           SemanticProperties.Hint="Double tap to submit the form" />
   ```

2. **HeadingLevel** - Cho phép screen reader điều hướng đúng
   ```xml
   <Label Text="Settings"
          SemanticProperties.HeadingLevel="Level1" />
   ```

3. **Font Scaling** - UI không bị vỡ khi người dùng tăng font size
   - Dùng Grid/FlexLayout thay vì HeightRequest cố định
   - Test với System Font Scale 200%

---

## Image & Icon Resources

### Single Project Resources

Đặt file SVG/PNG vào `Resources/Images`, MAUI tự động resize:

```xml
<!-- .csproj -->
<MauiImage Include="Resources\Images\*" />
<MauiIcon Include="Resources\AppIcon\appicon.svg" />
```

**KHÔNG CẦN** tạo `drawable-xhdpi`, `drawable-xxhdpi` thủ công.

---

## Common Mistakes / Lỗi Thường Gặp

| Mistake | Problem | Solution |
|---------|---------|----------|
| Hard-coded colors | Không thể re-brand | Dùng `{StaticResource}` |
| All resources in App.xaml | Khó maintain | Tách thành files riêng |
| Custom Renderers | Legacy Xamarin.Forms | Dùng Handlers |
| Missing Dark Mode | Poor UX | Dùng AppThemeBinding |
| AutomationProperties | Deprecated | Dùng SemanticProperties |
| Fixed HeightRequest | Vỡ UI khi font scale | Dùng Grid/FlexLayout |

---

## Quick Reference / Tham Chiếu Nhanh

| Category | Standard |
|----------|----------|
| Resource Organization | Tách `Colors.xaml`, `Typography.xaml`, `Theme.xaml` |
| Theme Support | `{AppThemeBinding Light=X, Dark=Y}` |
| Style Level 1 | XAML Styles + VisualStateManager |
| Style Level 2 | ControlTemplate + ContentPresenter |
| Style Level 3 | Handlers + AppendToMapping |
| Accessibility | SemanticProperties (NOT AutomationProperties) |
| Images | SVG preferred, `MauiImage` build action |
| Platform Code | Partial Classes trong `Platforms/` |

---

## Resources / Tài Nguyên

### Guidelines

- [Resource Architecture](./guidelines/resource-architecture.md) - ResourceDictionary patterns
- [Handler Customization](./guidelines/handler-customization.md) - Native control customization
- [Accessibility Rules](./guidelines/accessibility-rules.md) - WCAG compliance
- [Typography & Theme](./guidelines/typography-theme.md) - Font & Dark/Light mode

### Related Skills

- [MAUI Enterprise Architect](../maui-enterprise-architect/SKILL.md) - MVVM, DI, Shell patterns
- [Project Rules](../project-rules/SKILL.md) - GoodGo coding standards

### External

- [Microsoft MAUI Handlers](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/handlers/)
- [MAUI Styles & Themes](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/styles/xaml)
- [MAUI Accessibility](https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/accessibility)
