From dotnet-wpf
Guia de design profissional para WPF/XAML com Fluent Design (WPF-UI). Catalogo de solucoes documentadas para problemas de layout, espacamento, tipografia, sizing de controles e dark theme. Use quando o usuario quiser: corrigir layout de formulario WPF; ajustar espacamento entre campos; resolver toolbar/header que rola junto com conteudo; aumentar tamanho de controles pequenos ou com texto cortado; melhorar respiro visual entre secoes; aplicar tipografia Fluent Design; usar cores corretas de dark theme; diagnosticar problemas de ScrollViewer aninhado; alinhar labels com campos; auditar qualidade visual de uma pagina XAML. Tambem use quando o usuario mencionar "design WPF", "layout XAML", "campos pequenos", "texto cortado", "espacamento", "respiro", "controle apertado", "formulario feio", "dark theme cores", "Fluent Design tokens", "ScrollViewer problema", ou "toolbar rola". NAO use para: setup inicial de projeto (use dotnet-desktop-setup), MVVM/ViewModel (use dotnet-wpf-mvvm), testes E2E (use dotnet-wpf-e2e-testing), logica de negocio, APIs, deploy.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dotnet-wpf:dotnet-wpf-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Skill para diagnosticar e corrigir problemas de design em interfaces WPF/XAML, aplicando
Skill para diagnosticar e corrigir problemas de design em interfaces WPF/XAML, aplicando boas praticas do Microsoft Fluent Design System e WPF-UI.
Usa progressive disclosure — este arquivo contem o workflow, cookbook de solucoes e
tabela de tokens essenciais. Guias detalhados com exemplos completos ficam em references/
e sao lidos sob demanda.
v1.1.0 (2026-04-01)
references/wpfui-controls-catalog.mdv1.0.0 (2026-04-01)
Estes sao os valores mais usados. Para tabelas completas, leia references/typography-colors.md.
| Token | Valor | Uso comum |
|---|---|---|
| XS | 4px | Margem minima entre elementos inline |
| S | 8px | Entre botoes, controle e header |
| M | 12px | Entre controle e label, entre cards |
| L | 16px | Padding de superficie, margem de pagina |
| XL | 20px | Espacamento medio entre secoes |
| XXL | 24px | Entre campos de formulario (padrao Fluent) |
| XXXL | 32px | Entre grupos de campos |
| Controle | Altura padrao | Altura compacta |
|---|---|---|
| TextBox | 32px | 24px |
| ComboBox | 32-44px | 24px |
| Button | 32px | 24px |
| ToggleButton | 32px | 28px |
| Touch target minimo | 24x24 (WCAG AA) | — |
| Touch target recomendado | 40x40 | — |
| Estilo | Tamanho | Peso | Uso |
|---|---|---|---|
| Caption | 12px | Regular | Textos auxiliares, hints |
| Body | 14px | Regular | Labels, texto padrao |
| Body Strong | 14px | SemiBold | Sub-headers de secao |
| Body Large | 18px | Regular | Subtitulos |
| Subtitle | 20px | SemiBold | Titulos de grupo |
| Title | 28px | SemiBold | Titulo de pagina |
| Title Large | 40px | SemiBold | Hero text, splash |
| Display | 68px | SemiBold | Numeros grandes, dashboards |
| Elemento | Cor | Brush WPF-UI |
|---|---|---|
| Background app | #202020 | SolidBackgroundFillColorBase |
| Card/secao | #0DFFFFFF | CardBackgroundFillColorDefault |
| Texto primario | #FFFFFF | TextFillColorPrimaryBrush |
| Texto secundario | #C5FFFFFF (~77%) | TextFillColorSecondaryBrush |
| Texto desabilitado | #5DFFFFFF (~36%) | TextFillColorDisabledBrush |
| Borda controle | #12FFFFFF | ControlStrokeColorDefault |
| Separador/divider | #15FFFFFF | DividerStrokeColorDefault |
Leia o XAML da pagina e aplique este checklist:
Layout:
ScrollViewer.CanContentScroll="False"?Height="*", nao dentro de StackPanel?Espacamento:
Sizing:
Tipografia:
Theme:
#555?TextFillColorSecondaryBrush em vez de #B0B0B0?Para cada problema encontrado, consulte o cookbook abaixo e aplique a solucao documentada.
Para detalhes e exemplos completos, leia o arquivo correspondente em references/.
dotnet build — confirmar que compila sem errosProblema: Botoes de toolbar rolam junto com o conteudo da pagina quando hospedada
dentro de um NavigationView do WPF-UI.
Causa raiz: O NavigationViewContentPresenter do WPF-UI envolve o conteudo da pagina
em um DynamicScrollViewer interno (propriedade IsDynamicScrollViewerEnabled = true).
Isso faz com que o Grid inteiro da pagina (incluindo toolbar em Row 0) role.
Solucao: Adicionar ScrollViewer.CanContentScroll="False" no elemento <Page>:
<Page
x:Class="MeuProjeto.Pages.MinhaPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
ScrollViewer.CanContentScroll="False"
Loaded="Page_Loaded">
<Grid>
<Grid.RowDefinitions>
<RowDefinition Height="Auto" /> <!-- Toolbar: fica fixa -->
<RowDefinition Height="*" /> <!-- Conteudo: rola independente -->
</Grid.RowDefinitions>
<StackPanel Grid.Row="0" Orientation="Horizontal">
<!-- botoes da toolbar -->
</StackPanel>
<ScrollViewer Grid.Row="1" VerticalScrollBarVisibility="Auto">
<!-- conteudo scrollavel -->
</ScrollViewer>
</Grid>
</Page>
Como funciona: O NavigationViewContentPresenter le
ScrollViewer.GetCanContentScroll(page). Quando retorna false, seta
IsDynamicScrollViewerEnabled = false, removendo o wrapper DynamicScrollViewer.
Referencia: WPF-UI GitHub Issue #1041, PR #1504
Regra geral:
LastChildFill="True" para o conteudo principal.Por que nao usar StackPanel para formularios: StackPanel oferece espaco infinito
na direcao de orientacao. Isso impede que controles com Width="*" se expandam e
que ScrollViewer calcule a viewport corretamente.
Detalhes em references/layout-patterns.md.
Problema 1: ScrollViewer dentro de StackPanel nao rola
StackPanel da altura infinita ao ScrollViewer, que entao nao precisa rolar.
Fix: Colocar ScrollViewer em Grid com Height="*".
Problema 2: ScrollViewers aninhados Dois ScrollViewers competem pelo scroll do mouse. Fix: Manter apenas um ScrollViewer por eixo. O interno rola conteudo, o externo nao deve existir (ou ser desabilitado).
Detalhes em references/layout-patterns.md.
Problema: Campos de formulario muito juntos, sem respiro visual.
Solucao Fluent Design:
| Contexto | Margin recomendado |
|---|---|
| Entre campos (row margin) | Margin="0,12,0,0" (compacto) ou Margin="0,24,0,0" (padrao) |
| Entre grupos/secoes | Margin="0,32,0,0" ou Margin="0,48,0,0" |
| Padding de secao (Border) | Padding="16,12,16,16" |
| Entre botoes | Margin="0,0,8,0" |
| Entre label e campo (vertical) | Margin="0,0,0,8" no label |
Antes (apertado):
<RowDefinition Height="Auto" /> <!-- Margin="0,4" = 4px, muito pouco -->
<TextBlock Margin="0,4" />
Depois (confortavel):
<RowDefinition Height="Auto" /> <!-- Margin="0,12" = 12px compacto -->
<TextBlock Margin="0,12,0,0" /> <!-- ou Margin="0,8" para 8px simetrico -->
Detalhes em references/form-design.md.
Problema: TextBox, ComboBox ou controles customizados muito pequenos, texto cortado ou ilegivel.
Valores minimos recomendados:
| Controle | MinHeight | MinWidth | FontSize |
|---|---|---|---|
| TextBox | 32px | — | 14px (Body) |
| ComboBox | 32px | 100px | 14px |
| ToggleButton | 28px | 48px | 12px (Caption) |
| UserControl (date/time) | 32px | — | 13-14px |
| ComboBox (mes abreviado) | 32px | 80px | 13px |
| TextBox (2 digitos) | 32px | 40px | 13px |
| TextBox (4 digitos) | 32px | 55px | 13px |
Exemplo — controle de data (AptDateWPF):
<UserControl Height="32">
<StackPanel Orientation="Horizontal">
<TextBox Width="40" FontSize="13" MinHeight="28" />
<TextBlock Text="/" Margin="4,0" FontSize="13" />
<ComboBox Width="80" FontSize="13" MinHeight="28" />
<TextBlock Text="/" Margin="4,0" FontSize="13" />
<TextBox Width="55" FontSize="13" MinHeight="28" />
</StackPanel>
</UserControl>
Detalhes em references/controls-sizing.md.
Problema: Cores como #B0B0B0, #555, #444 hardcoded no XAML nao acompanham
mudancas de tema e podem ter contraste inadequado.
Solucao: Usar DynamicResource com brushes do WPF-UI:
<!-- Antes (hardcoded) -->
<TextBlock Foreground="#B0B0B0" />
<Border BorderBrush="#555" />
<!-- Depois (theme-aware) -->
<TextBlock Foreground="{DynamicResource TextFillColorSecondaryBrush}" />
<Border BorderBrush="{DynamicResource ControlStrokeColorDefaultBrush}" />
Mapeamento de cores comuns:
| Hardcoded | DynamicResource equivalente |
|---|---|
#B0B0B0 (label) | TextFillColorSecondaryBrush |
#555 (borda) | ControlStrokeColorDefaultBrush |
#444 (separador) | DividerStrokeColorDefaultBrush |
White (texto) | TextFillColorPrimaryBrush |
#2D2D30 (card bg) | CardBackgroundFillColorDefaultBrush |
Detalhes em references/wpfui-components.md.
Problema: FontSize inconsistente entre controles, headers, labels.
Solucao: Seguir o type ramp do Windows 11:
<!-- Titulo da pagina -->
<TextBlock FontSize="28" FontWeight="SemiBold" /> <!-- Title -->
<!-- Header de secao -->
<TextBlock FontSize="14" FontWeight="SemiBold" /> <!-- Body Strong -->
<!-- Label de campo -->
<TextBlock FontSize="14" /> <!-- Body -->
<!-- Texto auxiliar / hint -->
<TextBlock FontSize="12" /> <!-- Caption -->
Com WPF-UI (preferivel):
<ui:TextBlock FontTypography="Title" Text="Titulo" />
<ui:TextBlock FontTypography="BodyStrong" Text="Secao" />
<ui:TextBlock FontTypography="Body" Text="Label" />
<ui:TextBlock FontTypography="Caption" Text="Hint" />
Detalhes em references/typography-colors.md.
Problema: O projeto usa controles WPF padrao (TextBox, ComboBox) quando existem equivalentes WPF-UI com funcionalidades extras (PlaceholderText, Icon, ClearButton).
Controles mais uteis para formularios:
| Controle WPF-UI | Substitui | Vantagem |
|---|---|---|
ui:TextBox | TextBox | PlaceholderText, Icon, ClearButtonEnabled |
ui:NumberBox | TextBox (numerico) | Validacao, Min/Max, SpinButtons, MaxDecimalPlaces |
ui:AutoSuggestBox | TextBox + filtro | Dropdown de sugestoes, busca integrada |
ui:ToggleSwitch | CheckBox/ToggleButton | On/Off semantico, OnContent/OffContent |
ui:CalendarDatePicker | UserControl custom | Calendario popup nativo |
ui:ContentDialog | MessageBox.Show() | Modal async, DI-friendly, Fluent styled |
ui:Snackbar | — | Toast temporario para feedback (sucesso/erro) |
Catalogo completo com exemplos XAML em references/wpfui-controls-catalog.md.
Problema: Botoes importantes (Export PDF, Delete) nao se distinguem visualmente.
Solucao: Usar Appearance nos ui:Button:
<ui:Button Content="Export PDF" Appearance="Primary" /> <!-- Accent color -->
<ui:Button Content="Delete" Appearance="Danger" /> <!-- Vermelho -->
<ui:Button Content="Save" Appearance="Success" /> <!-- Verde -->
<ui:Button Content="Warning" Appearance="Caution" /> <!-- Laranja -->
<ui:Button Content="Cancel" Appearance="Secondary" /> <!-- Neutro -->
Valores disponiveis: Primary, Secondary, Info, Dark, Light, Danger, Success, Caution, Transparent.
StackPanel como container de formulario — StackPanel da espaco infinito e impede
controles Width="*" de expandir. Use Grid com ColumnDefinitions.
ScrollViewer dentro de StackPanel — o ScrollViewer recebe altura infinita e nunca
rola. Sempre coloque ScrollViewer em Grid com RowDefinition Height="*".
Cores hardcoded (#B0B0B0, #555) — nao acompanham mudanca de tema. Use
DynamicResource com brushes do WPF-UI.
FontSize < 12px — ilegivel. Minimo absoluto e 12px (Caption). Body text deve ser 14px.
Controles sem MinHeight — TextBox e ComboBox ficam microscopicos quando o conteudo e vazio. Sempre defina MinHeight >= 32px.
Margin="0,4" entre campos — 4px e muito pouco respiro. Minimo recomendado: 8px. Padrao Fluent: 24px.
Width fixo em ComboBox muito estreito — ComboBox com Width=65 nao mostra "Jun." completo com padding. Minimo: 80px para meses abreviados.
Height fixo em UserControl sem MinHeight nos filhos — o UserControl tem Height=27 mas os controles internos podem precisar de mais espaco. Defina MinHeight nos filhos.
ScrollViewer.CanContentScroll="False" e a unica forma confiavel de desabilitar o
DynamicScrollViewer do NavigationView no WPF-UI 4.2.0. ScrollViewer.VerticalScrollBarVisibility="Disabled" no Page NAO funciona — o NavigationViewContentPresenter ignora essa propriedade.
WPF-UI herda do Frame — o NavigationViewContentPresenter estende Frame, nao
ContentPresenter. Isso significa que a pagina nao recebe constraints de tamanho
automaticamente como em ContentPresenter.
DynamicResource vs StaticResource — para cores de tema, SEMPRE use DynamicResource.
StaticResource nao atualiza quando o tema muda em runtime.
ComboBox items com espacos iniciais — se os ComboBoxItems usam Content=" Good"
com espacos para padding, considere usar Padding em vez de espacos. Espacos podem
causar problemas ao comparar valores.
ContentDialogHost e o elemento XAML correto — nao usar ContentPresenter ou
ContentDialogPresenter. O elemento correto do WPF-UI 4.2.0 e <ui:ContentDialogHost>.
using Wpf.Ui.Extensions; necessario para ShowSimpleDialogAsync — este e um
extension method, nao um metodo da interface. Sem o using, o codigo compila mas
o metodo nao e encontrado.
using Wpf.Ui.Controls; conflita com System.Windows.Controls — TextBox, ComboBox,
Page, Button existem em ambos namespaces. Usar type aliases para tipos especificos do
WPF-UI: using ControlAppearance = Wpf.Ui.Controls.ControlAppearance;
async void so em event handlers UI — metodos como SaveFormDataJSON, LoadFormDataJSON
que usam await _contentDialogService.ShowSimpleDialogAsync() devem ser async Task,
nao async void. Excecoes em async void nao sao observaveis e podem crashar a app.
Leia estes arquivos somente quando necessario no passo correspondente:
| Arquivo | Leia quando... |
|---|---|
references/layout-patterns.md | Problemas de ScrollViewer, toolbar fixa, Grid vs StackPanel |
references/form-design.md | Espacamento entre campos, label alignment, respiro |
references/typography-colors.md | FontSize, type ramp, cores dark theme, contraste WCAG |
references/controls-sizing.md | MinHeight/MinWidth, ComboBox, TextBox, touch targets |
references/wpfui-components.md | Card, CardExpander, InfoBar, DynamicResource brushes, ControlAppearance, DI services |
references/wpfui-controls-catalog.md | Catalogo completo de 90+ controles WPF-UI com exemplos XAML |
references/sources.md | URLs de documentacao oficial e fontes da pesquisa |
npx claudepluginhub j0ruge/skills_commands_manager --plugin dotnet-wpfDesigns WinUI 3 UIs and reviews XAML for correctness, covering layout planning, control selection, Fluent Design, theming (Light/Dark/HighContrast), typography, spacing, brushes, accessibility, and data binding.
Guides WPF control authoring decisions: UserControl vs Control vs FrameworkElement selection, and Style/Template/Trigger alternatives. Use when creating new controls.
Building WPF on .NET 8+. Host builder, MVVM Toolkit, Fluent theme, performance, modern C# patterns.