From b4bdd9fe3500811b194dbc9c802abfa79984cfbf Mon Sep 17 00:00:00 2001 From: Nikola Metulev <711864+nmetulev@users.noreply.github.com> Date: Fri, 22 May 2026 16:28:03 -0700 Subject: [PATCH 01/12] winui-design: clean-room rewrite from public sources, ~60% size reduction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebuilt the skill from scratch using only public Microsoft Learn design docs (learn.microsoft.com/en-us/windows/apps/design/) and the WinUI Gallery (github.com/microsoft/WinUI-Gallery). Independent fresh-design experiment confirmed both topic coverage and content density. Structure (29 KB total, down from 73 KB): - SKILL.md (always loaded) - references/control-selection.md (control/pattern picking) - references/theme-accessibility.md (brushes, theme dicts, HC, a11y) - references/layout-review.md (page design, responsive, typography) - references/sources.md (public source URLs) Inline runnable samples are deferred to winui-search.exe (already shipped with the skill); exhaustive brush catalogues are deferred to Microsoft Learn. Unique high-signal items preserved: - WinUI 3 window-sizing rubric + GetDpiForWindow DllImport - TextBox x:Bind TwoWay + UpdateSourceTrigger=PropertyChanged gotcha - Attached-property C# setter pattern (vs object-initializer trap) - Acrylic BackgroundSizing + ThemeShadow Translation/padding rules Verification: line-overlap scan against windows-hivemind/windows-xaml plugin shows 9 lines of accidental match across all 5 files, all of which are syntactically-required XAML scaffolding tags and InitializeComponent() — zero copyrightable content shared. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- plugins/winui/skills/winui-design/SKILL.md | 314 ++++++++---------- .../references/approved-brushes.md | 160 --------- .../references/code-review-checklist.md | 114 ------- .../references/colors-and-materials.md | 106 ------ .../references/control-selection.md | 74 +++++ .../winui-design/references/control-styles.md | 91 ----- .../references/iconography-and-motion.md | 103 ------ .../winui-design/references/layout-review.md | 90 +++++ .../references/pr-review-patterns.md | 186 ----------- .../skills/winui-design/references/sources.md | 18 + .../references/theme-accessibility.md | 133 ++++++++ .../references/theme-aware-resources.md | 172 ---------- .../references/typography-and-spacing.md | 63 ---- 13 files changed, 453 insertions(+), 1171 deletions(-) delete mode 100644 plugins/winui/skills/winui-design/references/approved-brushes.md delete mode 100644 plugins/winui/skills/winui-design/references/code-review-checklist.md delete mode 100644 plugins/winui/skills/winui-design/references/colors-and-materials.md create mode 100644 plugins/winui/skills/winui-design/references/control-selection.md delete mode 100644 plugins/winui/skills/winui-design/references/control-styles.md delete mode 100644 plugins/winui/skills/winui-design/references/iconography-and-motion.md create mode 100644 plugins/winui/skills/winui-design/references/layout-review.md delete mode 100644 plugins/winui/skills/winui-design/references/pr-review-patterns.md create mode 100644 plugins/winui/skills/winui-design/references/sources.md create mode 100644 plugins/winui/skills/winui-design/references/theme-accessibility.md delete mode 100644 plugins/winui/skills/winui-design/references/theme-aware-resources.md delete mode 100644 plugins/winui/skills/winui-design/references/typography-and-spacing.md diff --git a/plugins/winui/skills/winui-design/SKILL.md b/plugins/winui/skills/winui-design/SKILL.md index ff4e081..95d8949 100644 --- a/plugins/winui/skills/winui-design/SKILL.md +++ b/plugins/winui/skills/winui-design/SKILL.md @@ -1,60 +1,150 @@ --- name: winui-design -description: "WinUI 3 UI design and XAML correctness — layout planning, control selection, Fluent Design, theming (Light/Dark/HighContrast), typography styles, spacing, brushes, accessibility, data binding review. Use when designing new pages, converting from WPF/Electron/web, reviewing XAML, fixing theme issues, or applying Fluent Design." +description: "Use when designing, reviewing, or fixing WinUI 3 / Windows App SDK UI: layout planning, control choice, Fluent Design alignment, Light/Dark/High Contrast theming, typography, spacing, brushes, accessibility, and XAML data-binding design. Load before authoring new XAML, reviewing UI PRs, migrating desktop UI to WinUI, or choosing between WinUI controls/patterns." --- -### UI Planning +# WinUI 3 UI design skill -> **Before picking controls, search the catalogue.** This skill ships `winui-search.exe` alongside this `SKILL.md`. It indexes 100+ WinUI Gallery controls, every Windows Community Toolkit scenario, and a curated set of platform integration patterns (JumpList, Share, file pickers, drag-drop). Use it to ground every control choice in a real shipping sample **before writing any XAML** — this is the difference between guessing property names and copying canonical code. -> -> ```powershell -> .\winui-search.exe search "" "" ... # batch one focused query per feature -> .\winui-search.exe get ... # batch up to 3 IDs — full XAML + C# + pitfall notes -> .\winui-search.exe list # browse all patterns (heavy — prefer search) -> .\winui-search.exe update # force refresh now -> ``` -> -> **Workflow:** in **one** `search` call, list every feature you need for the current page (one focused query per feature, not a bag of keywords) → from each shortlist pick the best ID → grab full code with `get` (batch up to 3 IDs per call) → then write XAML using those samples as reference. **Do NOT interleave searching with coding** — front-load all lookups, then code. BM25 rewards focused per-query phrasing, so keep each query about one control or pattern. +This skill adds a **WinUI-specific decision discipline**. It does not replace docs or samples: use `winui-search.exe` for runnable XAML/C# and Microsoft Learn for API details. -#### Step 1: Identify App Type and Anchor Control -| App Type | Anchor Control | Reference App | -|----------|---------------|---------------| -| Settings / config tool | `NavigationView` Left + `SettingsCard` | Windows Settings | -| Document / session editor | `TabView` + full-width content | Windows Terminal, Notepad | -| Hierarchical browser | `TreeView` + `ListView` + `BreadcrumbBar` | File Explorer | -| Developer tool / dashboard | `NavigationView` + card layout | Dev Home | -| Single-purpose utility | Mode switcher + compact grid | Calculator | +## Non-negotiable workflow -#### Step 2: Map Requirements to Controls -**Navigation:** 2-7 sections → `NavigationView`; document tabs → `TabView`; breadcrumb trail → `BreadcrumbBar`; 2-3 modes → `SelectorBar`. +1. **State the UI job first**: primary user task, secondary tasks, content density, expected window widths, input modes, and accessibility risks. +2. **Search the local catalogue before inventing XAML.** This skill ships `winui-search.exe` alongside this `SKILL.md` (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, curated platform-integration patterns; full XAML + C# + pitfall notes per result). + ```powershell + .\winui-search.exe search "" "" ... # batch one focused query per feature (BM25 rewards focused phrasing) + .\winui-search.exe get ... # batch up to 3 IDs — full XAML + C# + pitfall notes + .\winui-search.exe list # browse all patterns (heavy — prefer search) + .\winui-search.exe update # force cache refresh + ``` + **Workflow:** in **one** `search` call, list every feature you need for the current page → from each shortlist pick the best ID → grab full code with `get` (batch up to 3 per call) → then write XAML using those samples as reference. **Do NOT interleave searching with coding** — front-load lookups, then code. +3. **Design in effective pixels**, not physical pixels. Layout sizes, margins, and positions should generally be multiples of **4 epx**. +4. **Use platform controls before custom UI.** Custom visuals must preserve keyboard, UI Automation, focus, contrast themes, and theme switching. +5. **Review in four modes before calling it done**: Light, Dark, High Contrast/Contrast themes, and keyboard-only + screen reader names. -**Data display:** Vertical list → `ListView`; tiles/grid → `GridView` or `ItemsRepeater` + `UniformGridLayout`; hierarchy → `TreeView`; tabular → `ListView` with Grid column headers; master-detail → `ListView` + detail `Grid`. +## What to load on demand -**Input:** Text → `TextBox`; number → `NumberBox`; search → `AutoSuggestBox`; date → `CalendarDatePicker`; boolean → `ToggleSwitch`; pick one from 2-3 → `RadioButtons`; pick one from 4+ → `ComboBox`. +- `references/control-selection.md` — when selecting controls/patterns or reviewing whether a chosen control is appropriate. +- `references/theme-accessibility.md` — before adding brushes, theme dictionaries, visual states, custom controls, or High Contrast support. +- `references/layout-review.md` — when designing pages, navigation, responsive behavior, spacing, or typography hierarchy. -**Feedback:** Blocking decision → `ContentDialog`; contextual action → `Flyout`/`MenuFlyout`; onboarding → `TeachingTip`; inline status → `InfoBar`; system notification → `AppNotification`. +If a task is small, keep those references unloaded and use the checklists below. -#### Step 3: Plan Layout -- **Content fills the window** — no floating cards on empty backgrounds -- `Grid` for structure, `StackPanel` only for simple stacking of few items -- Sidebar: fixed 300-360px width; main content: `Width="*"` with 24px padding -- Status bar: `Grid` row at bottom; toolbar: `CommandBar` or title bar buttons +## Fast design triage -#### Step 4: Size the Window to the App +Ask and answer these before writing XAML: -> **WinUI 3 has no `SizeToContent`.** Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. **Size the window in `MainWindow`'s constructor; derive from the layout, not a generic.** +| Question | Good answer | Red flag | +|---|---|---| +| What is the page's primary action or decision? | One obvious task; commands support it. | Equal visual weight for everything. | +| Which app silhouette fits? | Left nav, top nav, tabbed/document, menu/command-focused, list-detail, or single-task form. | Navigation chosen because it is familiar, not because structure demands it. | +| What happens below 640 epx, 641-1007 epx, and 1008+ epx? | Reposition, resize, reflow, show/hide, or re-architect is specified. | Fixed desktop-only layout. | +| What content can truncate? | Text has wrapping/trimming strategy and accessible full value if needed. | Clipped labels, unreadable columns, hidden required info. | +| What is custom-colored? | Semantic brush resources with Light/Dark/HighContrast behavior. | Hard-coded foreground/background colors. | +| How does keyboard traversal work? | Logical tab order, focus visible, shortcuts documented where useful. | Pointer-only affordances. | + +## Layout rules that prevent most WinUI design defects + +- Use a **standard silhouette** unless the product has a specific reason not to: `NavigationView` for app sections, `TabView` for user-managed documents/workspaces, `Frame` for multi-page navigation, `BreadcrumbBar` for deep hierarchy. +- Keep top-level navigation shallow. More than ~7 peer pages or clear parent/child relationships usually needs hierarchy; avoid deep hierarchies unless breadcrumbs or equivalent escape routes exist. +- Avoid pogo-sticking: if users repeatedly go up one level then down another to compare related content, use list-detail, tabs, split view, filters, or adjacent panes. +- Prefer responsive changes in this order: **reflow/reposition** content, then **show/hide** secondary metadata, then **re-architect** only when the task changes materially by width. +- Do not confuse monitor pixels with XAML effective pixels. Breakpoints are based on app-window width: small `<640`, medium `641-1007`, large `>=1008` epx. +- Use multiples of 4 epx for layout measurements. Use smaller margins only for dense utility/editor surfaces; use larger margins for content/media surfaces where cohesion matters. + +## Control choice: default biases + +Use native controls for semantics, accessibility, and theme behavior. If unsure, search samples: + +```powershell +winui-search.exe search "navigationview settings layout" +winui-search.exe search "list details responsive" +winui-search.exe search "high contrast custom brush" +``` + +| Need | Prefer | Avoid | +|---|---|---| +| App sections | `NavigationView` left or top | Hand-built nav lists. | +| User-opened documents/workspaces | `TabView` | NavigationView tabs for closeable documents. | +| Hierarchical location | `BreadcrumbBar`, `TreeView` | Deep hidden back-stack only. | +| Primary page commands | `CommandBar`, buttons in clear command area | Random icon buttons without labels/tooltips. | +| One-of-many choice | `RadioButtons` / radio group | ComboBox when all options should be visible. | +| Many options, compact | `ComboBox` | Radio group with long scrolling list. | +| On/off setting | `ToggleSwitch` | Checkbox for persistent binary settings where switch semantics are clearer. | +| Select multiple independent options | `CheckBox` | ToggleSwitch grid when options are not settings. | +| Collections | `ListView`/`GridView`/`ItemsView` | ItemsRepeater unless you need primitive layout control. | +| Forms | labeled inputs, validation, submit affordance | Placeholder-only labels. | +| Contextual teaching | `TeachingTip` sparingly | Modal dialog for non-blocking education. | +| Blocking decision | `ContentDialog` | Dialogs for routine information. | + +## Theming and brushes + +- Use `{ThemeResource ...}` for values that must update when Light/Dark/HighContrast changes at runtime. +- Use existing WinUI theme brushes and type ramp resources before defining new resources. +- For custom semantic colors, define resources by **purpose**, not hue: `WarningTextBrush`, `ChartProfitBrush`, `CardBackgroundBrush`; not `OrangeBrush`. +- Custom theme dictionaries should explicitly cover `Light`, `Dark`, and `HighContrast` when the resource affects visible UI. +- In `ThemeDictionaries`, use `{StaticResource}` for theme-local resource definitions; exception: system/accent resources such as `SystemAccentColor` and `SystemColor...` may be `{ThemeResource}`. +- Do not override system contrast colors to preserve branding. Respect user contrast choices. +- Accent color is for emphasis/interactive state, not decoration. Never rely on color alone to communicate status. + +High Contrast rule of thumb: backgrounds pair with their matching foregrounds. Examples: `SystemColorWindowColor` + `SystemColorWindowTextColor`; `SystemColorHighlightColor` + `SystemColorHighlightTextColor`; `SystemColorButtonFaceColor` + `SystemColorButtonTextColor`. + +## Typography + +- Default font should be Segoe UI Variable via WinUI defaults; do not force a custom app font without product need. +- Use the XAML type ramp resources: `CaptionTextBlockStyle`, `BodyTextBlockStyle`, `BodyStrongTextBlockStyle`, `BodyLargeTextBlockStyle`, `BodyLargeStrongTextBlockStyle`, `SubtitleTextBlockStyle`, `TitleTextBlockStyle`, `TitleLargeTextBlockStyle`, `DisplayTextBlockStyle`. +- Use Semibold rather than Bold for emphasis in the Windows type ramp. +- Use sentence case for UI text. +- Body text should normally be left aligned; center alignment is exceptional, such as short labels under icons. +- Keep readable text lines roughly 50-60 characters when possible; avoid very narrow or very long measures. +- Do not make normal UI text smaller than 12 px regular or 14 px semibold. + +## Accessibility review + +A WinUI screen is not done until these pass: + +- Every meaningful interactive element has an accessible name. Do not rely on icon shape or color. +- Keyboard-only users can reach and operate every feature in a logical order. `ListView`/`GridView` already provide arrow-key patterns; custom controls must match expected keyboard behavior. +- Focus visuals are visible in Light, Dark, and High Contrast. +- Text, icons, states, and charts do not use color as the only differentiator. +- Media has play/pause/stop controls and captions or alternative audio when relevant. +- Custom controls expose appropriate UI Automation peers/patterns or are replaced with native controls. +- Validation errors are announced or associated with fields, not only painted red. +- Hit targets and spacing work for touch, pen, mouse, and keyboard; do not optimize only for pointer precision. + +## Data binding and MVVM design + +- Prefer binding UI state to view-model state instead of code-behind toggling visual properties. +- For WinUI 3, use `x:Bind` when compile-time checking and performance matter, and ordinary `{Binding}` where dynamic DataContext scenarios require it. +- Ensure `x:Bind` default mode is understood: it is `OneTime` unless set otherwise. Use `Mode=OneWay` or `TwoWay` intentionally. +- Use `INotifyPropertyChanged` for mutable displayed state and observable collections for dynamic lists. +- Do not put business logic in converters or code-behind event handlers; converters should be small presentation adapters. +- For design review, verify empty/loading/error states are represented in the view model and visible in UI. + +## Review output format + +When reviewing a WinUI UI change, return findings grouped as: + +1. **Blocking** — likely broken accessibility, theme failure, unusable layout, wrong control semantics. +2. **Should fix** — inconsistent Fluent/WinUI pattern, responsive gap, weak typography hierarchy, avoidable custom UI. +3. **Polish** — spacing, content density, command placement, labels. +4. **Need sample/doc check** — cases where `winui-search.exe` or Microsoft Learn should be consulted before coding. + +For each finding include: issue, user impact, concrete fix, and sample search query if applicable. + +## Window sizing (WinUI 3 specifics) + +> **WinUI 3 has no `SizeToContent`.** Without an explicit size, Windows defaults the main window to ~1024×768 — oversized for most utilities. Size the window in `MainWindow`'s constructor; derive from the layout, not a generic. **Rubric.** Width = widest row + 48 padding (24 each side), rounded **up** to nearest 20. Height = 32 (titlebar) + Σ(row heights) + Σ(spacing) + 48 padding, rounded up to 20. Round up — clipped content is a worse failure than a slightly-wide window. -**Sanity check** (ranges, not targets — derive yours from the rubric): +**Sanity ranges** (derive yours from the rubric, these are not targets): - Single-purpose utility → ~440–560 wide - Form / single-page tool → ~600–800 wide, ~640–800 tall - Multi-pane (nav + content) → ~1100–1300 wide, ~720–840 tall - Document / canvas / media editor → 1280+ wide -If your derived number is well below its range, you missed a row — re-check. - -`AppWindow.Resize` takes **physical pixels**, not DIPs — multiply by the monitor's DPI scale: +`AppWindow.Resize` takes **physical pixels**, not DIPs — multiply by the monitor's DPI scale. `XamlRoot.RasterizationScale` is null in the constructor and stale after `AppWindow.Move`, so `[DllImport] GetDpiForWindow` is the cleanest path: ```csharp using Microsoft.UI; @@ -77,145 +167,17 @@ public sealed partial class MainWindow : Window } ``` -`XamlRoot.RasterizationScale` is null in the ctor and stale after `AppWindow.Move`, so `[DllImport]` is the cleanest path. Don't try to size the window by setting `Width`/`Height` on the root `Grid` — that clips content, not the window. - -If the user asks for UI validation, see `winui-ui-testing` Step 3.5 to verify the rubric against the visual checklist. - -#### Step 5: Design Anti-Patterns -| ❌ Don't | ✅ Do Instead | -|----------|--------------| -| Centered floating card on background | Content fills window with padding | -| Custom pill/segment tab switcher | `NavigationView` Top or `SelectorBar` | -| Equal-width 50/50 column split | Fixed sidebar (300-360px) + flexible main | -| Hardcoded colors (`#FF0000`) | `{ThemeResource}` brushes | -| `ScrollViewer` around `ListView` | ListView has built-in scrolling | -| Custom ControlTemplate for standard controls | Built-in controls with style overrides | - -### XAML Correctness - -#### Theming Rules -- **`{ThemeResource BrushName}`** at usage sites — updates on theme change -- **`{StaticResource}`** with `ResourceKey` redirects inside theme dictionaries — zero allocation -- **`ResourceKey` must end in `Brush`** (target the `SolidColorBrush`, not the `Color`) -- Always define all three variants: `x:Key="Light"`, `x:Key="Dark"`, `x:Key="HighContrast"` — never use `x:Key="Default"` -- Verify runtime theme switching: `{ThemeResource}` updates; `{StaticResource}` does not - -```xml - - +Don't try to size the window by setting `Width`/`Height` on the root `Grid` — that clips content, not the window. - - -``` - -#### High Contrast -Only 8 system color brushes allowed in HC dictionaries: - -| Background | Foreground | Use Case | -|------------|------------|----------| -| `SystemColorWindowColorBrush` | `SystemColorWindowTextColorBrush` | General content | -| `SystemColorHighlightColorBrush` | `SystemColorHighlightTextColorBrush` | Selected/hover | -| `SystemColorButtonFaceColorBrush` | `SystemColorButtonTextColorBrush` | Buttons | -| `SystemColorWindowColorBrush` | `SystemColorHotlightColorBrush` | Hyperlinks | -| `SystemColorWindowColorBrush` | `SystemColorGrayTextColorBrush` | Disabled content | - -**HC prohibitions:** No hardcoded colors, no opacity, no accent colors, no regular WinUI brushes, no `SystemColor*` in Light/Dark dicts. Use empty HC dict when WinUI defaults suffice. Set `HighContrastAdjustment = None` at app level. - -#### Typography — Use Styles, Not Raw FontSize -| Style | Size | Weight | Use For | -|-------|------|--------|---------| -| `CaptionTextBlockStyle` | 12px | Regular | Small labels, timestamps | -| `BodyTextBlockStyle` | 14px | Regular | Body text (default — don't set explicitly) | -| `BodyStrongTextBlockStyle` | 14px | Semibold | Emphasized body text | -| `SubtitleTextBlockStyle` | 20px | Semibold | Section headers, card titles | -| `TitleTextBlockStyle` | 28px | Semibold | Page titles | -| `TitleLargeTextBlockStyle` | 40px | Semibold | Large feature titles | -| `DisplayTextBlockStyle` | 68px | Semibold | Hero text | - -Use `SemiBold`, never `Bold`. Minimum 12px. `BasedOn` styles must not re-declare inherited properties. - -#### Spacing and Layout -- **4px grid:** margins, padding, sizes must be multiples of 4 (4, 8, 12, 16, 24, 32, 48) -- `ControlCornerRadius` (4px) for controls, `OverlayCornerRadius` (8px) for overlays — never hardcode -- `RowSpacing`/`ColumnSpacing` instead of spacer elements -- `MinHeight`/`MinWidth` instead of fixed sizing -- No negative margins - -#### Remove Defaults -Don't set WinUI default values — blocks future updates: -- `BodyTextBlockStyle` on TextBlock, `TextFillColorPrimaryBrush` foreground, `TextWrapping="NoWrap"`, `Padding="0"`, `Margin="0"` - -#### Acrylic Pairings -| Surface | Background | Border | -|---------|-----------|--------| -| Flyouts, tooltips | `AcrylicBackgroundFillColorDefaultBrush` | `SurfaceStrokeColorFlyoutBrush` | -| UI surfaces | `AcrylicBackgroundFillColorBaseBrush` | `SurfaceStrokeColorDefaultBrush` | - -Use `BackgroundSizing="InnerBorderEdge"` on bordered acrylic. `ThemeShadow` requires `Translation="0,0,32"` and 12px parent padding. - -#### Data Binding -- `{x:Bind}` over `{Binding}`, explicit `Mode=OneWay`/`TwoWay`, `x:DataType` on `DataTemplate` -- **TextBox `x:Bind TwoWay` — always add `UpdateSourceTrigger=PropertyChanged`** so the ViewModel updates on each keystroke instead of waiting for `LostFocus`. Without it, UIA automation (`set-value`) and programmatic changes won't commit to the ViewModel. - ```xml - - ``` -- Commands over Click/Tapped handlers (MVVM) -- `VisualStateManager` for visual property changes, not code-behind -- No `IValueConverter` — prefer `x:Bind` with functions - -**Bool negation and Visibility functions** — define static methods in code-behind: -```csharp -// In code-behind (e.g., MainPage.xaml.cs) -public static Visibility BoolToVisibility(bool value) => - value ? Visibility.Visible : Visibility.Collapsed; -public static Visibility InvertBoolToVisibility(bool value) => - value ? Visibility.Collapsed : Visibility.Visible; -public static bool IsNotBusy(bool isLoading) => !isLoading; -``` -```xml - -Visibility="{x:Bind local:MainPage.BoolToVisibility(ViewModel.IsLoading), Mode=OneWay}" -IsEnabled="{x:Bind local:MainPage.IsNotBusy(ViewModel.IsLoading), Mode=OneWay}" -``` -❌ NEVER use `Converter={x:Null}` — it crashes at runtime. - -#### Accessibility -- `AutomationProperties.Name` on icon-only controls -- `AutomationProperties.AutomationId` on all interactive controls -- Semantic controls (`Button`, `HyperlinkButton`) — not clickable `Border`/`TextBlock` -- `DividerStrokeColorDefaultBrush` for dividers - -**Setting attached properties in code-behind** — WinUI attached properties use static methods, NOT object initializer syntax: -```csharp -using Microsoft.UI.Xaml.Automation; // required for AutomationProperties - -// ❌ WRONG — object initializer doesn't work for attached properties -var btn = new Button { AutomationProperties = { AutomationId = "BtnSave" } }; - -// ✅ CORRECT — static setter method -var btn = new Button { Content = "Save" }; -AutomationProperties.SetAutomationId(btn, "BtnSave"); -AutomationProperties.SetName(btn, "Save button"); -Grid.SetRow(btn, 1); -Grid.SetColumn(btn, 0); -ToolTipService.SetToolTip(btn, "Save the current document"); -``` +## Anti-patterns -#### Formatting -- Self-closing tags for childless elements -- Styles referenced with `{StaticResource}` not `{ThemeResource}` -- No `px` suffix on numeric values, no commented-out XAML -- Consistent attribute order: x:Name, AutomationProperties, layout, content, style - -### References - -| File | Read when... | -|------|-------------| -| `references/approved-brushes.md` | Looking up correct WinUI brush names and usage rules | -| `references/theme-aware-resources.md` | Implementing ThemeResource/StaticResource, High Contrast, acrylic pairings | -| `references/code-review-checklist.md` | Reviewing XAML changes for correctness | -| `references/pr-review-patterns.md` | Applying concrete review fixes and patterns | -| `references/control-styles.md` | Customizing built-in control styles | -| `references/typography-and-spacing.md` | Detailed type ramp, spacing grid, and sizing examples | -| `references/colors-and-materials.md` | Theme brush catalog, Mica/Acrylic surface pairings, material usage | -| `references/iconography-and-motion.md` | Icon guidelines, animation patterns, connected animations | +- Copying web/mobile layout conventions without translating to Windows input, windowing, and keyboard expectations. +- Hard-coded `#RRGGBB` colors directly in controls. +- `StaticResource` for visible colors that must react to theme changes. +- Icons without labels, tooltips, or accessible names. +- Placeholder text used as the only field label. +- Hiding required commands at small widths with no alternate route. +- Modal dialogs for non-blocking hints. +- Custom list controls when `ListView`, `GridView`, `ItemsView`, or Gallery/Toolkit patterns already solve the scenario. +- Assuming Light/Dark support means High Contrast works. +- Designing only at full-screen desktop width. diff --git a/plugins/winui/skills/winui-design/references/approved-brushes.md b/plugins/winui/skills/winui-design/references/approved-brushes.md deleted file mode 100644 index 114b88f..0000000 --- a/plugins/winui/skills/winui-design/references/approved-brushes.md +++ /dev/null @@ -1,160 +0,0 @@ -# Approved Brushes - -When reviewing XAML, verify that every brush is either: -1. A custom brush with explicit `Light`, `Dark`, and `HighContrast` theme dictionaries, OR -2. One of the approved brushes listed below. - -If neither, request the author to switch to an approved brush or provide the complete theme-aware resource set. - -## Usage - -- `{ThemeResource BrushName}` at usage sites (updates on theme change) -- `{StaticResource BrushName}` inside theme dictionaries -- Names ending in `Brush` are `SolidColorBrush` resources; names without are `Color` resources -- Prefer the `Brush` key when assigning to Foreground/Background - -## Common System Brushes (Quick Reference) - -| Resource | Purpose | -|----------|---------| -| `TextFillColorPrimaryBrush` | Primary text | -| `TextFillColorSecondaryBrush` | Secondary text | -| `TextFillColorTertiaryBrush` | Tertiary / placeholder text | -| `TextFillColorDisabledBrush` | Disabled text | -| `AccentFillColorDefaultBrush` | Accent color fills | -| `ControlFillColorDefaultBrush` | Control backgrounds | -| `CardBackgroundFillColorDefaultBrush` | Card backgrounds | -| `LayerFillColorDefaultBrush` | Layer backgrounds | - -## Text Fill - - TextFillColorPrimary / TextFillColorPrimaryBrush - TextFillColorSecondary / TextFillColorSecondaryBrush - TextFillColorTertiary / TextFillColorTertiaryBrush - TextFillColorDisabled / TextFillColorDisabledBrush - TextFillColorInverse / TextFillColorInverseBrush - AccentTextFillColorPrimary / AccentTextFillColorPrimaryBrush - AccentTextFillColorSecondary / AccentTextFillColorSecondaryBrush - AccentTextFillColorTertiary / AccentTextFillColorTertiaryBrush - AccentTextFillColorDisabled / AccentTextFillColorDisabledBrush - TextOnAccentFillColorSelectedText / TextOnAccentFillColorSelectedTextBrush - TextOnAccentFillColorPrimary / TextOnAccentFillColorPrimaryBrush - TextOnAccentFillColorSecondary / TextOnAccentFillColorSecondaryBrush - TextOnAccentFillColorDisabled / TextOnAccentFillColorDisabledBrush - -## Control Fill - - ControlFillColorDefault / ControlFillColorDefaultBrush - ControlFillColorSecondary / ControlFillColorSecondaryBrush - ControlFillColorTertiary / ControlFillColorTertiaryBrush - ControlFillColorQuarternary / ControlFillColorQuarternaryBrush - ControlFillColorDisabled / ControlFillColorDisabledBrush - ControlFillColorTransparent / ControlFillColorTransparentBrush - ControlFillColorInputActive / ControlFillColorInputActiveBrush - ControlStrongFillColorDefault / ControlStrongFillColorDefaultBrush - ControlStrongFillColorDisabled / ControlStrongFillColorDisabledBrush - ControlSolidFillColorDefault / ControlSolidFillColorDefaultBrush - -## Subtle Fill - - SubtleFillColorTransparent / SubtleFillColorTransparentBrush - SubtleFillColorSecondary / SubtleFillColorSecondaryBrush - SubtleFillColorTertiary / SubtleFillColorTertiaryBrush - SubtleFillColorDisabled / SubtleFillColorDisabledBrush - -## Control Alt Fill - - ControlAltFillColorTransparent / ControlAltFillColorTransparentBrush - ControlAltFillColorSecondary / ControlAltFillColorSecondaryBrush - ControlAltFillColorTertiary / ControlAltFillColorTertiaryBrush - ControlAltFillColorQuarternary / ControlAltFillColorQuarternaryBrush - ControlAltFillColorDisabled / ControlAltFillColorDisabledBrush - -## Control On Image Fill - - ControlOnImageFillColorDefault / ControlOnImageFillColorDefaultBrush - ControlOnImageFillColorSecondary / ControlOnImageFillColorSecondaryBrush - ControlOnImageFillColorTertiary / ControlOnImageFillColorTertiaryBrush - ControlOnImageFillColorDisabled / ControlOnImageFillColorDisabledBrush - -## Accent Fill - - AccentFillColorSelectedTextBackground / AccentFillColorSelectedTextBackgroundBrush - AccentFillColorDefault / AccentFillColorDefaultBrush - AccentFillColorSecondary / AccentFillColorSecondaryBrush - AccentFillColorTertiary / AccentFillColorTertiaryBrush - AccentFillColorDisabled / AccentFillColorDisabledBrush - -## Stroke - - ControlStrokeColorDefault / ControlStrokeColorDefaultBrush - ControlStrokeColorSecondary / ControlStrokeColorSecondaryBrush - ControlStrokeColorOnAccentDefault / ControlStrokeColorOnAccentDefaultBrush - ControlStrokeColorOnAccentSecondary / ControlStrokeColorOnAccentSecondaryBrush - ControlStrokeColorOnAccentTertiary / ControlStrokeColorOnAccentTertiaryBrush - ControlStrokeColorOnAccentDisabled / ControlStrokeColorOnAccentDisabledBrush - ControlStrokeColorForStrongFillWhenOnImage / ControlStrokeColorForStrongFillWhenOnImageBrush - CardStrokeColorDefault / CardStrokeColorDefaultBrush - CardStrokeColorDefaultSolid / CardStrokeColorDefaultSolidBrush - ControlStrongStrokeColorDefault / ControlStrongStrokeColorDefaultBrush - ControlStrongStrokeColorDisabled / ControlStrongStrokeColorDisabledBrush - SurfaceStrokeColorDefault / SurfaceStrokeColorDefaultBrush - SurfaceStrokeColorFlyout / SurfaceStrokeColorFlyoutBrush - SurfaceStrokeColorInverse / SurfaceStrokeColorInverseBrush - DividerStrokeColorDefault / DividerStrokeColorDefaultBrush - FocusStrokeColorOuter / FocusStrokeColorOuterBrush - FocusStrokeColorInner / FocusStrokeColorInnerBrush - -## Background Fill - - CardBackgroundFillColorDefault / CardBackgroundFillColorDefaultBrush - CardBackgroundFillColorSecondary / CardBackgroundFillColorSecondaryBrush - CardBackgroundFillColorTertiary / CardBackgroundFillColorTertiaryBrush - SmokeFillColorDefault / SmokeFillColorDefaultBrush - LayerFillColorDefault / LayerFillColorDefaultBrush - LayerFillColorAlt / LayerFillColorAltBrush - LayerOnAcrylicFillColorDefault / LayerOnAcrylicFillColorDefaultBrush - LayerOnAccentAcrylicFillColorDefault / LayerOnAccentAcrylicFillColorDefaultBrush - LayerOnMicaBaseAltFillColorDefault / LayerOnMicaBaseAltFillColorDefaultBrush - LayerOnMicaBaseAltFillColorSecondary / LayerOnMicaBaseAltFillColorSecondaryBrush - LayerOnMicaBaseAltFillColorTertiary / LayerOnMicaBaseAltFillColorTertiaryBrush - LayerOnMicaBaseAltFillColorTransparent / LayerOnMicaBaseAltFillColorTransparentBrush - -## Solid Background Fill - - SolidBackgroundFillColorBase / SolidBackgroundFillColorBaseBrush - SolidBackgroundFillColorSecondary / SolidBackgroundFillColorSecondaryBrush - SolidBackgroundFillColorTertiary / SolidBackgroundFillColorTertiaryBrush - SolidBackgroundFillColorQuarternary / SolidBackgroundFillColorQuarternaryBrush - SolidBackgroundFillColorQuinary / SolidBackgroundFillColorQuinaryBrush - SolidBackgroundFillColorSenary / SolidBackgroundFillColorSenaryBrush - SolidBackgroundFillColorTransparent / SolidBackgroundFillColorTransparentBrush - SolidBackgroundFillColorBaseAlt / SolidBackgroundFillColorBaseAltBrush - -## System Fill - - SystemFillColorSuccess / SystemFillColorSuccessBrush - SystemFillColorCaution / SystemFillColorCautionBrush - SystemFillColorCritical / SystemFillColorCriticalBrush - SystemFillColorNeutral / SystemFillColorNeutralBrush - SystemFillColorSolidNeutral / SystemFillColorSolidNeutralBrush - SystemFillColorAttentionBackground / SystemFillColorAttentionBackgroundBrush - SystemFillColorSuccessBackground / SystemFillColorSuccessBackgroundBrush - SystemFillColorCautionBackground / SystemFillColorCautionBackgroundBrush - SystemFillColorCriticalBackground / SystemFillColorCriticalBackgroundBrush - SystemFillColorNeutralBackground / SystemFillColorNeutralBackgroundBrush - SystemFillColorSolidAttentionBackground / SystemFillColorSolidAttentionBackgroundBrush - SystemFillColorSolidNeutralBackground / SystemFillColorSolidNeutralBackgroundBrush - -## High Contrast System Brushes - -For `x:Key="HighContrast"` dictionaries only: - - SystemColorWindowTextColorBrush - SystemColorWindowColorBrush - SystemColorButtonFaceColorBrush - SystemColorButtonTextColorBrush - SystemColorHighlightColorBrush - SystemColorHighlightTextColorBrush - SystemColorHotlightColorBrush - SystemColorGrayTextColorBrush diff --git a/plugins/winui/skills/winui-design/references/code-review-checklist.md b/plugins/winui/skills/winui-design/references/code-review-checklist.md deleted file mode 100644 index 10c5a71..0000000 --- a/plugins/winui/skills/winui-design/references/code-review-checklist.md +++ /dev/null @@ -1,114 +0,0 @@ -# Code Review Checklist - -## Theme Support - -- [ ] Uses `{ThemeResource}` for colors/brushes at usage sites -- [ ] Uses `{StaticResource}` with `ResourceKey` redirects inside theme dictionaries -- [ ] Custom theme resources define `Light`, `Dark`, and `HighContrast` variants -- [ ] No `x:Key="Default"` — uses explicit `Light`/`Dark`/`HighContrast` -- [ ] `ResourceKey` values end in `Brush` (not the Color name) -- [ ] HC dictionary uses only the 8 system color brushes (no accent, no hardcoded, no WinUI brushes) -- [ ] No opacity on elements or brushes in HC dictionaries -- [ ] No HC resources (`SystemColor*`) used in Light/Dark dictionaries -- [ ] `StaticResource` redirects preferred over inline `SolidColorBrush` in theme dicts -- [ ] Theme dictionary `x:Key` order consistent across Light/Dark/HighContrast -- [ ] No partial theme updates — Light/Dark changes include matching HighContrast in same PR -- [ ] No ad-hoc themed literals (`White`/`Transparent` for themed surfaces) -- [ ] Acrylic surfaces use correct border/background pairings -- [ ] Light and Dark dicts reference the same semantic WinUI keys; differences are intentional -- [ ] Empty HC dict used when WinUI defaults suffice (``) -- [ ] `HighContrastAdjustment="None"` set at app level -- [ ] Accent colors use `SystemAccentColor*` resources (no hardcoded accent values) -- [ ] Verify runtime theme switching (ThemeResource updates; StaticResource does not) - -## Data Binding - -- [ ] Uses `{x:Bind}` over `{Binding}` where possible -- [ ] `Mode` explicitly set on `x:Bind` when values change (`OneWay`/`TwoWay`) -- [ ] `DataTemplate` has `x:DataType` specified -- [ ] No `IValueConverter` — uses `x:Bind` with functions -- [ ] Button text uses `Content` directly, not a nested `TextBlock` -- [ ] `IsEnabled` bound from ViewModel readiness state -- [ ] Commands used instead of Click/Tapped event handlers (MVVM) -- [ ] `VisualStateManager` used for visual property changes (not code-behind) -- [ ] ViewModel state mapped to named properties (bool/enum) instead of complex converter stacks -- [ ] Converters are only simple type conversions; business logic stays in ViewModel -- [ ] No code-behind for styles/colors/layout (exception: `HighContrastAdjustment` at app level) - -## Typography - -- [ ] Uses system text styles, not hardcoded font properties -- [ ] `FontWeight` is `SemiBold`, never `Bold` -- [ ] `BasedOn` styles do not re-declare inherited properties -- [ ] Default `TextFillColorPrimaryBrush` foreground not explicitly set -- [ ] No font sizes below 12px -- [ ] Icon TextBlocks set `IsTextScaleFactorEnabled="False"` -- [ ] Icon font uses `{ThemeResource SymbolThemeFontFamily}`, not hardcoded - -## Layout - -- [ ] Uses `ControlCornerRadius`/`OverlayCornerRadius` (not hardcoded) -- [ ] Selective corner rounding uses standard radii (e.g., `8,8,0,0`) -- [ ] Margins/padding use multiples of 4 -- [ ] Uses `MinHeight`/`MinWidth` instead of fixed sizing -- [ ] No fixed heights on text containers -- [ ] No fixed button widths (content-driven or `MinWidth`) -- [ ] `Border` for single-child containers (not nested Grids) -- [ ] `StackPanel` does not contain TextBlocks needing `TextTrimming` -- [ ] `RowSpacing`/`ColumnSpacing` used instead of spacer elements -- [ ] No negative margins -- [ ] `ThemeShadow` has `Translation="0,0,32"` and 12px parent padding -- [ ] Shadow receiver is behind the elevated element (z-order) -- [ ] `BackgroundSizing="InnerBorderEdge"` on bordered acrylic elements -- [ ] Mixed-control rows vertically centered - -## Styles - -- [ ] Styles referenced with `{StaticResource}` (not `{ThemeResource}`) -- [ ] Default WinUI property values not explicitly set (Padding, CornerRadius, etc.) -- [ ] Single-use styles inlined, named style deleted -- [ ] Existing WinUI styles checked before creating custom ones -- [ ] No no-op style churn -- [ ] App-specific resources stay in app or feature dictionaries -- [ ] `ThemeResource` used inside style setters for themed values -- [ ] VisualStateManager uses AdaptiveTrigger for responsive layout when needed -- [ ] Unused VisualState definitions removed - -## Resource Organization & Naming - -- [ ] Semantic resource keys used (avoid location-based names) -- [ ] Shared resources promoted only when reused across features -- [ ] One-off values remain local (no global resources for single-use) - -## Accessibility - -- [ ] `AutomationProperties.Name` on icon-only controls -- [ ] Light-dismiss targets are hit-test visible (`Background="Transparent"`) -- [ ] `DividerStrokeColorDefaultBrush` for dividers (not custom opacity brushes) - -## Performance - -- [ ] `x:Load` for conditional content -- [ ] `x:Phase` for list item incremental loading -- [ ] `OneTime` binding for static content -- [ ] Minimal container nesting - -## Formatting - -- [ ] Uniform indentation (spaces, no tabs) -- [ ] Self-closing tags for childless elements -- [ ] No `px` suffix on numeric values -- [ ] No commented-out XAML -- [ ] Unused VisualState definitions removed -- [ ] ThemeDictionaries before non-themed resources -- [ ] Namespace declarations ordered consistently (default, `x:`, platform, WinUI, local) -- [ ] Attribute order consistent across related files -- [ ] No checkpoint files checked in (use `_CP` locally and remove before commit) - -## Testing Reminders - -**If changing brushes:** Test in NightSky HC theme, hover on all interactive elements. Include Light/Dark/HC screenshot evidence. - -**If changing text/containers:** Test with text scaling at max and with long/localized strings. - -**If changing layout:** Test at 100%, 150%, 200%, 250% display scaling. Validate Figma at 100% scale. diff --git a/plugins/winui/skills/winui-design/references/colors-and-materials.md b/plugins/winui/skills/winui-design/references/colors-and-materials.md deleted file mode 100644 index caf424e..0000000 --- a/plugins/winui/skills/winui-design/references/colors-and-materials.md +++ /dev/null @@ -1,106 +0,0 @@ -# Colors and Materials Reference - -## Colors — Theme Resources - -**Never hardcode colors.** Always use `{ThemeResource}` brushes so your app works in Light, Dark, and High Contrast modes. - -### Text brushes - -| Resource | Use for | -|----------|---------| -| `TextFillColorPrimaryBrush` | Primary text (headings, body) | -| `TextFillColorSecondaryBrush` | Secondary / supporting text | -| `TextFillColorTertiaryBrush` | Pressed state text | -| `TextFillColorDisabledBrush` | Disabled text only | -| `TextOnAccentFillColorPrimaryBrush` | Text on accent-colored backgrounds | -| `AccentTextFillColorPrimaryBrush` | Hyperlinks and accent text | - -### Control fill brushes - -| Resource | Use for | -|----------|---------| -| `ControlFillColorDefaultBrush` | Control rest state | -| `ControlFillColorSecondaryBrush` | Control hover state | -| `ControlFillColorTertiaryBrush` | Control pressed state | -| `ControlFillColorDisabledBrush` | Disabled controls | -| `ControlFillColorInputActiveBrush` | Focused text input fields | - -### Background brushes - -| Resource | Use for | -|----------|---------| -| `CardBackgroundFillColorDefaultBrush` | Card backgrounds | -| `CardBackgroundFillColorSecondaryBrush` | Alternate card rows | -| `LayerFillColorDefaultBrush` | Layered surface backgrounds | -| `SolidBackgroundFillColorBaseBrush` | Opaque page backgrounds | -| `SmokeFillColorDefaultBrush` | Overlay dimming (behind dialogs) | -| `AcrylicBackgroundFillColorBaseBrush` | Acrylic material surfaces | - -### Accent fill (for primary action buttons) - -| Resource | Use for | -|----------|---------| -| `AccentFillColorDefaultBrush` | Primary button rest | -| `AccentFillColorSecondaryBrush` | Primary button hover | -| `AccentFillColorTertiaryBrush` | Primary button pressed | -| `AccentFillColorDisabledBrush` | Disabled primary button | - -### Stroke / border brushes - -| Resource | Use for | -|----------|---------| -| `CardStrokeColorDefaultBrush` | Card borders | -| `ControlStrokeColorDefaultBrush` | Control borders | -| `DividerStrokeColorDefaultBrush` | Separators and dividers | - -### Color code examples - -```xml - - - - - - - - - -``` - ---- - -## Materials — Mica & Acrylic - -**Mica** — use for the app's main window background. It samples the desktop wallpaper for a subtle tinted translucency. - -**Acrylic** — use for transient surfaces (flyouts, menus, sidebars) layered on top of the main window. - -```xml - - - - - - - - - - - - - - -``` - -| Material | Surface lifetime | Example | -|----------|-----------------|---------| -| **Mica** | Long-lived (app window) | Main window background | -| **Mica Base Alt** | Long-lived (alternate tint) | Secondary window background | -| **Acrylic** | Transient (overlays) | Flyouts, sidebars, command bars | - -Materials fall back to solid color on unsupported systems — no code needed. diff --git a/plugins/winui/skills/winui-design/references/control-selection.md b/plugins/winui/skills/winui-design/references/control-selection.md new file mode 100644 index 0000000..0898fef --- /dev/null +++ b/plugins/winui/skills/winui-design/references/control-selection.md @@ -0,0 +1,74 @@ +# WinUI control selection reference + +Load this when the UI task is mostly "which control/pattern should I use?" or when reviewing an existing choice. + +## First action + +Run `winui-search.exe search ""` before writing sample XAML. Use `get ` for the nearest Gallery/Toolkit example. This reference gives selection rules; the tool gives runnable code. + +## Navigation and structure + +| Scenario | Use | Notes | +|---|---|---| +| Multi-page app with stable sections | `NavigationView` + `Frame` | Left nav for broad app sections; top nav when options are few and content needs horizontal space. | +| User can open/close/reorder documents or workspaces | `TabView` | Think browser/editor tabs, not app-section navigation. | +| Deep hierarchy/location | `BreadcrumbBar` | Especially if users need to escape >2 levels. | +| Hierarchical data | `TreeView` | Avoid for flat page navigation unless hierarchy is the real task. | +| Master-detail content | List/details pattern | Collapse to single-pane navigation on narrow widths. | +| Dense editor/utility commands | `MenuBar` + `CommandBar` | Suitable for document/editing apps. | + +Navigation heuristics: +- Flat/lateral structure fits pages viewable in any order and fewer than about 8 clear peers. +- Hierarchical structure fits ordered tasks, parent/child relationships, or many pages. +- Avoid deep navigation and pogo-sticking; if users compare siblings often, keep related content adjacent. + +## Input controls + +| User need | Prefer | Why / cautions | +|---|---|---| +| Immediate action | `Button` | Use clear verb text. Primary action should be visually obvious. | +| Action with menu variants | `DropDownButton` / `SplitButton` | Use split only when default action is safe and common. | +| Binary setting | `ToggleSwitch` | Best for persistent on/off settings. | +| Independent selection | `CheckBox` | Good for multiple independent options. | +| Mutually exclusive small set | `RadioButtons` | Keeps all options visible. | +| Mutually exclusive larger/compact set | `ComboBox` | Do not hide critical choices if comparison matters. | +| Continuous value | `Slider` | Provide numeric value if precision matters. | +| Text entry | `TextBox`, `NumberBox`, `PasswordBox`, `RichEditBox` | Always provide visible label and validation. | +| Date/time | `CalendarDatePicker`, `DatePicker`, `TimePicker` | Prefer specialized pickers to freeform text. | + +## Collections + +| Scenario | Prefer | Avoid | +|---|---|---| +| Standard selectable vertical list | `ListView` | Custom ItemsRepeater with missing selection/focus. | +| Visual grid of items | `GridView` / `ItemsView` | Hand-laid WrapPanel-like grids. | +| Primitive virtualized custom layout | `ItemsRepeater` | Use only when you accept more responsibility for interaction/accessibility. | +| Paginated position indicator | `PipsPager` | Page-number UI when exact numbers are irrelevant. | +| Swipe actions on touch list items | `SwipeControl` | Hidden destructive actions with no non-touch route. | +| Pull refresh | `RefreshContainer` / pull-to-refresh pattern | Refresh gesture without visible command fallback. | + +Review collection states: empty, loading, error, selection, multiselect, keyboard navigation, virtualization, item accessible names. + +## Dialogs, flyouts, and teaching + +| Need | Use | Caution | +|---|---|---| +| User must decide before continuing | `ContentDialog` | Keep rare and focused. | +| Contextual lightweight choices | `Flyout` / `MenuFlyout` | Should be dismissible and keyboard reachable. | +| Teach a feature or call out new UI | `TeachingTip` | Do not block routine workflows. | +| Context commands near selection | `CommandBarFlyout`, context menu | Include keyboard/menu alternatives. | + +## Commands + +- Put primary commands where the task happens; do not scatter icon-only buttons. +- Use `CommandBar` when commands need overflow behavior. +- Destructive commands need confirmation or undo depending on severity. +- Icons need text labels, tooltips, or accessible names; ambiguous icons need visible text. + +## When to choose custom UI + +Only after all are true: +1. No platform control or Gallery/Toolkit pattern matches the task. +2. You can implement keyboard, focus, UI Automation, theme resources, High Contrast, and responsive behavior. +3. You have explicit visual/interaction specs for states: default, hover, pressed, disabled, selected, focused, error. +4. You tested with keyboard and contrast themes. diff --git a/plugins/winui/skills/winui-design/references/control-styles.md b/plugins/winui/skills/winui-design/references/control-styles.md deleted file mode 100644 index cd3d6bf..0000000 --- a/plugins/winui/skills/winui-design/references/control-styles.md +++ /dev/null @@ -1,91 +0,0 @@ -# Control Styles - -Built-in WinUI 3 styles and patterns. Use `{StaticResource}` to reference, `BasedOn` to extend. - -## Button Styles - -| Style | Description | -|-------|-------------| -| `DefaultButtonStyle` | Standard button | -| `AccentButtonStyle` | Accent-colored primary action button | -| `NavigationBackButtonNormalStyle` | Back navigation (40x40) | -| `NavigationBackButtonSmallStyle` | Small back navigation (30x30) | - -```xml - -``` - -Empty HC dictionary lets WinUI defaults apply. Light and Dark usually have identical redirects. Border brush states should match background states. - -## Typography Styles - -| Style | Size | Weight | Use Case | -|-------|------|--------|----------| -| `CaptionTextBlockStyle` | 12px | Regular | Small labels, timestamps | -| `BodyTextBlockStyle` | 14px | Regular | Default body text (applied by default) | -| `BaseTextBlockStyle` | 14px | Semibold | Base body style (less common) | -| `BodyStrongTextBlockStyle` | 14px | Semibold | Emphasized body text | -| `BodyLargeTextBlockStyle` | 18px | Regular | Prominent body text | -| `SubtitleTextBlockStyle` | 20px | Semibold | Section headers, card titles | -| `TitleTextBlockStyle` | 28px | Semibold | Page titles | -| `TitleLargeTextBlockStyle` | 40px | Semibold | Large feature titles | -| `DisplayTextBlockStyle` | 68px | Semibold | Hero text | - -**Rules:** -- `BodyTextBlockStyle` is the default — do not explicitly apply it. -- `TextWrapping="NoWrap"` is the default — do not set it. -- Use `SemiBold`, never `Bold`. -- Minimum 12px for CJK legibility. -- `BasedOn` styles must not re-declare inherited properties (FontSize, FontFamily, FontWeight, LineHeight). - -## Style Hygiene - -- Reference styles with `{StaticResource}` (not `{ThemeResource}` — unnecessary overhead). -- Check for existing WinUI styles before creating custom ones. -- Single-use styles: inline the properties, delete the named style. -- Keep one-off values inline; promote to shared dictionary only when reused. -- Prefer setters/resource overrides for minor visual tweaks; avoid replacing `ControlTemplate` unless structurally required. -- Use `ThemeResource` inside style setters for theme-dependent values. -- Avoid no-op style churn. - -## Naming Conventions - -| Type | Convention | Example | -|------|------------|---------| -| Style | `{Purpose}Style` | `PrimaryButtonStyle` | -| Brush | `{Usage}{Property}Brush` | `HeaderBackgroundBrush` | -| DataTemplate | `{DataType}Template` | `UserItemTemplate` | -| Element `x:Name` | PascalCase + suffix | `SearchTextBox`, `SaveButton` | diff --git a/plugins/winui/skills/winui-design/references/iconography-and-motion.md b/plugins/winui/skills/winui-design/references/iconography-and-motion.md deleted file mode 100644 index 51d9e86..0000000 --- a/plugins/winui/skills/winui-design/references/iconography-and-motion.md +++ /dev/null @@ -1,103 +0,0 @@ -# Iconography and Motion Reference - -## Iconography - -Use **Segoe Fluent Icons** (Windows 11) via the `SymbolThemeFontFamily` resource, which falls back to **Segoe MDL2 Assets** on Windows 10 automatically. - -### Icon types in order of preference - -| Type | When to use | Example | -|------|-------------|---------| -| `SymbolIcon` | Standard named icons (simplest) | `` | -| `FontIcon` | Specific glyph codes from Segoe Fluent Icons | `` | -| `AnimatedIcon` | Interactive states (checkbox, nav, toggle) | Built-in with some controls | -| `ImageIcon` | Custom brand icons or images | `` | -| `PathIcon` | Custom vector shapes | `` | -| `BitmapIcon` | Legacy bitmap icons | Avoid — prefer `ImageIcon` | - -**Standard icon sizes:** 16px (inline/compact), 20px (default control size), 24px (emphasis), 32px (large), 48px (hero/feature). - -### Icon code examples - -```xml - - - - - - - - - - - - -``` - -Browse available icons in the **WinUI Gallery** app → Design guidance → Iconography, or search [Segoe Fluent Icons](https://learn.microsoft.com/windows/apps/design/style/segoe-fluent-icons-font). - ---- - -## Corner Radius - -Use the **built-in theme resources** — never hardcode `CornerRadius` values: - -| Resource | Value | Use for | -|----------|-------|---------| -| `ControlCornerRadius` | 4px | In-page controls (buttons, inputs, list items) | -| `OverlayCornerRadius` | 8px | Top-level containers (cards, dialogs, flyouts, app window) | -| 0px | — | Edges that intersect with other straight edges (no resource needed) | - -```xml - - - - - - - - - - - -``` - -### Connected animations - -Animate elements between pages (e.g., list item → detail page): - -```csharp -// Source page — prepare animation -var service = ConnectedAnimationService.GetForCurrentView(); -service.PrepareToAnimate("itemAnimation", sourceElement); -Frame.Navigate(typeof(DetailPage), item); - -// Destination page — play animation -var animation = ConnectedAnimationService.GetForCurrentView() - .GetAnimation("itemAnimation"); -animation?.TryStart(destinationElement); -``` diff --git a/plugins/winui/skills/winui-design/references/layout-review.md b/plugins/winui/skills/winui-design/references/layout-review.md new file mode 100644 index 0000000..358e3cf --- /dev/null +++ b/plugins/winui/skills/winui-design/references/layout-review.md @@ -0,0 +1,90 @@ +# WinUI layout, typography, and responsive review reference + +Load this for page design, responsive behavior, spacing, and text hierarchy. + +## Page planning template + +Before XAML, write these bullets in your own notes or review: +- Primary user task: +- Secondary tasks: +- Content type/density: +- Navigation structure: flat / hierarchical / hybrid: +- App silhouette: left nav / top nav / tabs / menu+command / list-detail / single-task: +- Breakpoint behavior: small `<640`, medium `641-1007`, large `>=1008` epx: +- Input modes: keyboard, mouse, touch, pen: +- Accessibility risks: + +## Responsive techniques + +Prefer the least disruptive technique that preserves the task: + +| Technique | Use when | Example | +|---|---|---| +| Reposition | Same content fits better elsewhere | Move side details below main content on narrow width. | +| Resize | Same content needs different space | Wider reading column or larger media preview. | +| Reflow | Content sequence can wrap/change columns | One column becomes two columns at large width. | +| Show/hide | Secondary metadata is optional at small widths | Hide avatar/details, keep route to full info. | +| Re-architect | Width changes the usable task model | Single-pane list/detail becomes side-by-side master-detail. | + +Breakpoints are app-window effective pixels, not physical screen pixels: +- Small: `<640` epx. +- Medium: `641-1007` epx. +- Large: `>=1008` epx. + +## Spacing and density + +- Use multiples of 4 epx for layout sizes, margins, and positions. +- Dense utility/editor surfaces can use tighter margins such as 12 epx when task efficiency matters. +- Content/media surfaces can use larger margins such as 56 epx when cohesion and focus matter. +- Keep related controls visually grouped; separate unrelated groups with spacing, headers, or containers. +- Do not fake grouping using color-only backgrounds that fail in themes. + +## Typography + +Use XAML type ramp resources rather than ad-hoc font sizes: + +| Purpose | Style | +|---|---| +| Caption/supplemental | `CaptionTextBlockStyle` | +| Body | `BodyTextBlockStyle` | +| Body emphasis | `BodyStrongTextBlockStyle` | +| Larger body | `BodyLargeTextBlockStyle` | +| Larger body emphasis | `BodyLargeStrongTextBlockStyle` | +| Section/subtitle | `SubtitleTextBlockStyle` | +| Page title | `TitleTextBlockStyle` | +| Large page/hero title | `TitleLargeTextBlockStyle` | +| Display/marketing hero | `DisplayTextBlockStyle` | + +Rules: +- Segoe UI Variable is the default system font; avoid forcing custom fonts. +- Use Semibold for emphasis; avoid Bold/Italic as routine UI hierarchy. +- Sentence case for UI text. +- Left-align most text. Center only for short, exceptional compositions such as text below icons. +- Keep body lines around 50-60 characters where possible. +- Plan truncation: wrapping, ellipsis, clipping, tooltip/detail route, or column resize. + +## Navigation review + +- Can users identify where they are? +- Is the way back/out obvious? +- Are peer pages at the same level, not mixed with children from another subtree? +- Does a hierarchy deeper than two levels provide breadcrumbs or equivalent context? +- Are top-level navigation labels clear without relying on icons? +- Is content reachable without pogo-sticking? + +## Empty/loading/error states + +Every data-driven page should specify: +- Loading: progress and status text. +- Empty: what happened and what action the user can take. +- Error: cause if known, retry/repair action, non-color-only indication. +- Offline/permission states if applicable. +- Selection states for lists/grids, including keyboard behavior. + +## XAML binding design checks + +- `x:Bind` mode is explicit when the value changes (`OneWay`/`TwoWay`); remember default is `OneTime`. +- View model exposes mutable state with property change notifications. +- Collections that change after load are observable. +- Visual states derive from view state, not scattered event handlers. +- Converters are simple presentation adapters, not business logic. diff --git a/plugins/winui/skills/winui-design/references/pr-review-patterns.md b/plugins/winui/skills/winui-design/references/pr-review-patterns.md deleted file mode 100644 index d1a9737..0000000 --- a/plugins/winui/skills/winui-design/references/pr-review-patterns.md +++ /dev/null @@ -1,186 +0,0 @@ -# Review Guidance Patterns - -Concrete guidance patterns for WinUI 3 XAML reviews. Use these as a checklist for common pitfalls and fixes. - -## 1. Brush References Must Target Brush Resources - -`ResourceKey` must reference the `SolidColorBrush` resource (suffix `Brush`), not the `Color` resource. - -```xml - - - - - -``` - -Applies to High Contrast as well: - -```xml - - - - - -``` - -## 2. Prefer StaticResource Redirects Over Inline SolidColorBrush - -Inline brushes allocate new objects. Redirect to existing WinUI brushes instead: - -```xml - - - - - -``` - -## 3. High Contrast Rules (Strict) - -- Only use the 8 system color brushes in HighContrast dictionaries. -- No hardcoded colors, no opacity, no accent colors, no regular WinUI brushes in HC. -- No gradient animations in HC. Use a single SystemColor brush. -- Use `{ThemeResource}` only for `SystemColor*` in HC; use `{StaticResource}` elsewhere. -- Use empty HC dictionary when WinUI defaults suffice: - `` -- Set `HighContrastAdjustment = ApplicationHighContrastAdjustment.None` once at app level. - -## 4. Remove Defaults and Redundant Properties - -Avoid setting WinUI default values; it blocks future updates. - -```xml - - +``` + +Don't rely on the glyph alone — screen readers won't announce "save icon" without `AutomationProperties.Name`. + +### Reusing an icon definition + +Define once in `App.xaml`, consume anywhere via `IconSourceElement`: + +```xml + + +``` +```xml + + + +``` + +### IconElement-bearing controls (cheat-sheet) + +Controls whose `Icon` property takes an `IconElement`: +- `AppBarButton`, `AppBarToggleButton` +- `MenuFlyoutItem`, `MenuFlyoutSubItem` +- `AutoSuggestBox.QueryIcon` +- `NavigationViewItem` +- `SelectorBarItem` + +Controls whose `IconSource` property takes an `IconSource`: +- `TabViewItem`, `SwipeItem` +- `InfoBar`, `InfoBadge` +- `TeachingTip` +- `XamlUICommand` +- `AnimatedIcon.FallbackIconSource`, `AnimatedIconSource.FallbackIconSource` + +If you find yourself wrapping a `FontIcon` in `IconSourceElement` repeatedly, you've picked the wrong slot — switch the parent's property to its `IconSource`-typed sibling if it exists. From 8bf9115c3e48994f0b07b23256e020e903efb20f Mon Sep 17 00:00:00 2001 From: Nikola Metulev <711864+nmetulev@users.noreply.github.com> Date: Fri, 22 May 2026 17:17:37 -0700 Subject: [PATCH 03/12] winui-design: trim skill ~36% after 5-model review panel MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A 5-model review panel (Sonnet 4.6, GPT-5.4, GPT-5.3-Codex, Opus 4.6, Opus 4.7) unanimously rated the skill USEFUL-BUT-OVERSIZED and asked for roughly half cut. This commit delivers that, focused on the consensus findings. SKILL.md (15.5 -> 10.1 KB): - Cut typography section, generic a11y checklist, generic MVVM bullets, control-choice bias table, review-output-format ceremony, and fast- triage table — all duplicated training data or process-theater - Added: sidebar XAML skeleton (NavigationView + SettingsCard + ScrollViewer), Mica/SystemBackdrop wiring with the don't-paint-root trap, CommunityToolkit.WinUI.Controls.SettingsControls package note, PaneDisplayMode enumeration — all were gaps the panel flagged - Promoted the high-signal landmines (x:Bind OneTime default, TextBox UpdateSourceTrigger, attached-property setters, Converter={x:Null}, acrylic+ThemeShadow) into a dedicated 'XAML landmines' section references/control-selection.md: DELETED (~90% duplicated SKILL.md; unique custom-UI gate merged into anti-patterns) references/sources.md: DELETED (bibliography agents can't click; citations live inline in brushes-and-icons.md) references/layout-review.md (4 -> 2.5 KB): kept page-planning template, responsive-techniques table, state-coverage checklist, sidebar sizing heuristics; cut typography (model knows the type ramp), spacing duplication, navigation review, XAML binding duplication references/theme-accessibility.md (6.2 -> 3.1 KB): lead with deep ThemeDictionary patterns (ResourceKey redirect, runtime theme switching, BasedOn discipline); generic a11y/keyboard/media checklists removed (now in training) references/brushes-and-icons.md: trimmed the Smoke section (one brush, ContentDialog applies it automatically) Verified zero prose overlap with the windows-xaml plugin via 8-gram shingle scan (only shared content is XAML scaffolding tokens and learn.microsoft.com URL fragments). Independent verification (Opus 4.7, blind to panel recs): verdict USEFUL, trim successful, sidebar skeleton + SettingsCard package note + Mica wiring + window-sizing DPI code each materially change generated output. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- plugins/winui/skills/winui-design/SKILL.md | 274 ++++++++---------- .../references/brushes-and-icons.md | 6 - .../references/control-selection.md | 74 ----- .../winui-design/references/layout-review.md | 98 ++----- .../skills/winui-design/references/sources.md | 18 -- .../references/theme-accessibility.md | 132 ++------- 6 files changed, 181 insertions(+), 421 deletions(-) delete mode 100644 plugins/winui/skills/winui-design/references/control-selection.md delete mode 100644 plugins/winui/skills/winui-design/references/sources.md diff --git a/plugins/winui/skills/winui-design/SKILL.md b/plugins/winui/skills/winui-design/SKILL.md index 0d4ef4f..b92f7f4 100644 --- a/plugins/winui/skills/winui-design/SKILL.md +++ b/plugins/winui/skills/winui-design/SKILL.md @@ -5,173 +5,77 @@ description: "Use when designing, reviewing, or fixing WinUI 3 / Windows App SDK # WinUI 3 UI design skill -This skill adds a **WinUI-specific decision discipline**. It does not replace docs or samples: use `winui-search.exe` for runnable XAML/C# and Microsoft Learn for API details. +This skill is **the sharp-edges expert** for WinUI 3 — landmines that bite, conventions that aren't obvious, and a sample-search tool. Trust your own training for the basics (NavigationView vs TabView, the type ramp, generic accessibility); load this for what the basics don't tell you. -## Non-negotiable workflow +## Search samples before writing XAML -1. **State the UI job first**: primary user task, secondary tasks, content density, expected window widths, input modes, and accessibility risks. -2. **Search the local catalogue before inventing XAML.** This skill ships `winui-search.exe` alongside this `SKILL.md` (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, curated platform-integration patterns; full XAML + C# + pitfall notes per result). - ```powershell - .\winui-search.exe search "" "" ... # batch one focused query per feature (BM25 rewards focused phrasing) - .\winui-search.exe get ... # batch up to 3 IDs — full XAML + C# + pitfall notes - .\winui-search.exe list # browse all patterns (heavy — prefer search) - .\winui-search.exe update # force cache refresh - ``` - **Workflow:** in **one** `search` call, list every feature you need for the current page → from each shortlist pick the best ID → grab full code with `get` (batch up to 3 per call) → then write XAML using those samples as reference. **Do NOT interleave searching with coding** — front-load lookups, then code. -3. **Design in effective pixels**, not physical pixels. Layout sizes, margins, and positions should generally be multiples of **4 epx**. -4. **Use platform controls before custom UI.** Custom visuals must preserve keyboard, UI Automation, focus, contrast themes, and theme switching. -5. **Review in four modes before calling it done**: Light, Dark, High Contrast/Contrast themes, and keyboard-only + screen reader names. +This skill ships `winui-search.exe` alongside this `SKILL.md` (≈100 WinUI Gallery controls, every Windows Community Toolkit scenario, curated platform-integration patterns; each result returns full XAML + C# + pitfall notes). **Front-load lookups, then code** — don't interleave. -## What to load on demand - -- `references/control-selection.md` — when selecting controls/patterns or reviewing whether a chosen control is appropriate. -- `references/theme-accessibility.md` — before adding brushes, theme dictionaries, visual states, custom controls, or High Contrast support. -- `references/layout-review.md` — when designing pages, navigation, responsive behavior, spacing, or typography hierarchy. -- `references/brushes-and-icons.md` — when looking up a specific brush key, deciding which icon type to use, or referencing the full WinUI brush catalogue. - -If a task is small, keep those references unloaded and use the checklists below. +```powershell +.\winui-search.exe search "" "" ... # batch one focused query per feature (BM25 likes focused phrasing) +.\winui-search.exe get ... # batch up to 3 IDs — full XAML + C# + pitfall notes +.\winui-search.exe list # browse all patterns (heavy — prefer search) +.\winui-search.exe update # force cache refresh +``` ## App-shape anchors -Pick the closest shipping Windows app as a mental model before laying out a new page. The anchor tells you which silhouette and what density to aim for. +Pick the closest shipping app silhouette before laying out a page: | App type | Anchor controls | Reference app | |----------|-----------------|---------------| -| Settings / config tool | `NavigationView` Left + `SettingsCard` | Windows Settings | +| Settings / config tool | `NavigationView` Left + `SettingsCard` / `SettingsExpander` | Windows Settings | | Document / session editor | `TabView` + full-width content | Windows Terminal, Notepad | | Hierarchical browser | `TreeView` + `ListView` + `BreadcrumbBar` | File Explorer | | Developer tool / dashboard | `NavigationView` + card layout | Dev Home | | Single-purpose utility | Mode switcher + compact grid | Calculator | -## Fast design triage - -Ask and answer these before writing XAML: - -| Question | Good answer | Red flag | -|---|---|---| -| What is the page's primary action or decision? | One obvious task; commands support it. | Equal visual weight for everything. | -| Which app silhouette fits? | Left nav, top nav, tabbed/document, menu/command-focused, list-detail, or single-task form. | Navigation chosen because it is familiar, not because structure demands it. | -| What happens below 640 epx, 641-1007 epx, and 1008+ epx? | Reposition, resize, reflow, show/hide, or re-architect is specified. | Fixed desktop-only layout. | -| What content can truncate? | Text has wrapping/trimming strategy and accessible full value if needed. | Clipped labels, unreadable columns, hidden required info. | -| What is custom-colored? | Semantic brush resources with Light/Dark/HighContrast behavior. | Hard-coded foreground/background colors. | -| How does keyboard traversal work? | Logical tab order, focus visible, shortcuts documented where useful. | Pointer-only affordances. | - -## Layout rules that prevent most WinUI design defects - -- Use a **standard silhouette** unless the product has a specific reason not to: `NavigationView` for app sections, `TabView` for user-managed documents/workspaces, `Frame` for multi-page navigation, `BreadcrumbBar` for deep hierarchy. -- Keep top-level navigation shallow. More than ~7 peer pages or clear parent/child relationships usually needs hierarchy; avoid deep hierarchies unless breadcrumbs or equivalent escape routes exist. -- Avoid pogo-sticking: if users repeatedly go up one level then down another to compare related content, use list-detail, tabs, split view, filters, or adjacent panes. -- Prefer responsive changes in this order: **reflow/reposition** content, then **show/hide** secondary metadata, then **re-architect** only when the task changes materially by width. -- Do not confuse monitor pixels with XAML effective pixels. Breakpoints are based on app-window width: small `<640`, medium `641-1007`, large `>=1008` epx. -- Use multiples of 4 epx for layout measurements. Use smaller margins only for dense utility/editor surfaces; use larger margins for content/media surfaces where cohesion matters. - -## Control choice: default biases - -Use native controls for semantics, accessibility, and theme behavior. If unsure, search samples: - -```powershell -winui-search.exe search "navigationview settings layout" -winui-search.exe search "list details responsive" -winui-search.exe search "high contrast custom brush" -``` +`SettingsCard` and `SettingsExpander` are **not in WinUI itself** — install `CommunityToolkit.WinUI.Controls.SettingsControls` and add `xmlns:tk="using:CommunityToolkit.WinUI.Controls"`. -| Need | Prefer | Avoid | -|---|---|---| -| App sections | `NavigationView` left or top | Hand-built nav lists. | -| User-opened documents/workspaces | `TabView` | NavigationView tabs for closeable documents. | -| Hierarchical location | `BreadcrumbBar`, `TreeView` | Deep hidden back-stack only. | -| Primary page commands | `CommandBar`, buttons in clear command area | Random icon buttons without labels/tooltips. | -| One-of-many choice | `RadioButtons` / radio group | ComboBox when all options should be visible. | -| Many options, compact | `ComboBox` | Radio group with long scrolling list. | -| On/off setting | `ToggleSwitch` | Checkbox for persistent binary settings where switch semantics are clearer. | -| Select multiple independent options | `CheckBox` | ToggleSwitch grid when options are not settings. | -| Collections | `ListView`/`GridView`/`ItemsView` | ItemsRepeater unless you need primitive layout control. | -| Forms | labeled inputs, validation, submit affordance | Placeholder-only labels. | -| Contextual teaching | `TeachingTip` sparingly | Modal dialog for non-blocking education. | -| Blocking decision | `ContentDialog` | Dialogs for routine information. | - -## Theming and brushes - -- Use `{ThemeResource ...}` for values that must update when Light/Dark/HighContrast changes at runtime. -- Use existing WinUI theme brushes and type ramp resources before defining new resources. -- For custom semantic colors, define resources by **purpose**, not hue: `WarningTextBrush`, `ChartProfitBrush`, `CardBackgroundBrush`; not `OrangeBrush`. -- Custom theme dictionaries should explicitly cover `Light`, `Dark`, and `HighContrast` when the resource affects visible UI. -- In `ThemeDictionaries`, use `{StaticResource}` for theme-local resource definitions; exception: system/accent resources such as `SystemAccentColor` and `SystemColor...` may be `{ThemeResource}`. -- Do not override system contrast colors to preserve branding. Respect user contrast choices. -- Accent color is for emphasis/interactive state, not decoration. Never rely on color alone to communicate status. - -High Contrast rule of thumb: backgrounds pair with their matching foregrounds. Examples: `SystemColorWindowColor` + `SystemColorWindowTextColor`; `SystemColorHighlightColor` + `SystemColorHighlightTextColor`; `SystemColorButtonFaceColor` + `SystemColorButtonTextColor`. - -## Typography - -- Default font should be Segoe UI Variable via WinUI defaults; do not force a custom app font without product need. -- Use the XAML type ramp resources: `CaptionTextBlockStyle`, `BodyTextBlockStyle`, `BodyStrongTextBlockStyle`, `BodyLargeTextBlockStyle`, `BodyLargeStrongTextBlockStyle`, `SubtitleTextBlockStyle`, `TitleTextBlockStyle`, `TitleLargeTextBlockStyle`, `DisplayTextBlockStyle`. -- Use Semibold rather than Bold for emphasis in the Windows type ramp. -- Use sentence case for UI text. -- Body text should normally be left aligned; center alignment is exceptional, such as short labels under icons. -- Keep readable text lines roughly 50-60 characters when possible; avoid very narrow or very long measures. -- Do not make normal UI text smaller than 12 px regular or 14 px semibold. - -## Accessibility review - -A WinUI screen is not done until these pass: - -- Every meaningful interactive element has an accessible name. Do not rely on icon shape or color. -- Keyboard-only users can reach and operate every feature in a logical order. `ListView`/`GridView` already provide arrow-key patterns; custom controls must match expected keyboard behavior. -- Focus visuals are visible in Light, Dark, and High Contrast. -- Text, icons, states, and charts do not use color as the only differentiator. -- Media has play/pause/stop controls and captions or alternative audio when relevant. -- Custom controls expose appropriate UI Automation peers/patterns or are replaced with native controls. -- Validation errors are announced or associated with fields, not only painted red. -- Hit targets and spacing work for touch, pen, mouse, and keyboard; do not optimize only for pointer precision. - -## Data binding and MVVM design - -- Prefer binding UI state to view-model state instead of code-behind toggling visual properties. -- For WinUI 3, use `x:Bind` when compile-time checking and performance matter, and ordinary `{Binding}` where dynamic DataContext scenarios require it. -- Ensure `x:Bind` default mode is understood: it is `OneTime` unless set otherwise. Use `Mode=OneWay` or `TwoWay` intentionally. -- Use `INotifyPropertyChanged` for mutable displayed state and observable collections for dynamic lists. -- Do not put business logic in converters or code-behind event handlers; converters should be small presentation adapters. -- For design review, verify empty/loading/error states are represented in the view model and visible in UI. - -### x:Bind functions instead of converters - -Prefer static functions over `IValueConverter` for the common bool→Visibility / negation cases. Declare them once in code-behind: - -```csharp -// In code-behind, e.g. MainPage.xaml.cs -public static Visibility BoolToVisibility(bool value) => - value ? Visibility.Visible : Visibility.Collapsed; -public static Visibility InvertBoolToVisibility(bool value) => - value ? Visibility.Collapsed : Visibility.Visible; -public static bool Not(bool value) => !value; -``` +## Sidebar skeleton (Settings-style page) ```xml - -