winui: window sizing rubric, screenshot validation, anti-self-delegation

plugins/winui/agents/winui-dev.agent.md

@@ -4,6 +4,10 @@ description: "Builds WinUI 3 desktop applications using Windows App SDK, XAML, a
 user-invocable: true
 ---
 
+## You Are The WinUI Developer — Do The Work Yourself
+
+You are `winui-dev` — don't call `task` with `agent_type: "winui:winui-dev"` (self-hop). `task` is fine for scoped helpers (`explore` for parallel codebase mapping, `general-purpose` for rubber-duck critique), not for the build itself.
+
 ## Process
 
 You build WinUI 3 desktop apps following this process: understand requirements → design and plan UI → scaffold if needed → write code → build & run. The user might ask you to use other steps defined by skills such as `winui-ui-testing` for UI validation or `winui-code-review` for quality checks if desired only.

plugins/winui/skills/winui-design/SKILL.md

@@ -40,7 +40,48 @@ description: "WinUI 3 UI design and XAML correctness — layout planning, contro
 - Sidebar: fixed 300-360px width; main content: `Width="*"` with 24px padding
 - Status bar: `Grid` row at bottom; toolbar: `CommandBar` or title bar buttons
 
-#### Step 4: Design Anti-Patterns
+#### Step 4: Size the Window to the App
+
+> **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):
+- 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:
+
+```csharp
+using Microsoft.UI;
+using Microsoft.UI.Windowing;
+using System.Runtime.InteropServices;
+using Windows.Graphics;
+
+public sealed partial class MainWindow : Window
+{
+    [DllImport("user32.dll")]
+    private static extern uint GetDpiForWindow(IntPtr hWnd);
+
+    public MainWindow()
+    {
+        InitializeComponent();
+        var hwnd  = Win32Interop.GetWindowFromWindowId(AppWindow.Id);
+        var scale = GetDpiForWindow(hwnd) / 96.0;
+        AppWindow.Resize(new SizeInt32((int)(460 * scale), (int)(860 * scale)));
+    }
+}
+```
+
+`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 |

plugins/winui/skills/winui-ui-testing/SKILL.md

@@ -101,6 +101,11 @@ if ($missingId.Count -eq 0) {
     $results += @{ name = "AutomationId coverage"; status = "FAIL"; detail = "Missing: $names" }
 }
 
+# ─── State Screenshots (capture each meaningful state for visual review) ───
+New-Item -ItemType Directory -Force -Path "screenshots" | Out-Null
+winapp ui screenshot -a $AppPid -o "screenshots/01-initial.png" 2>$null
+# ...take more screenshots after key interactions above (mode switches, dialogs opened, etc.)
+
 # ─── Final Screenshot ───
 winapp ui screenshot -a $AppPid -o "test-screenshot.png" 2>$null
 
@@ -140,6 +145,25 @@ Write tests for **every requirement** from the user's prompt:
 
 Read `test-results.json` for structured pass/fail. Only fix code if tests fail.
 
+### Step 3.5: Look at the Screenshots
+
+UIA assertions don't see clipping, overlap, wrong theming, or controls bleeding past their container — UIA returns `PASS` while the app is visually broken. **Capture screenshots with `winapp ui screenshot` and view each PNG.**
+
+Capture the initial state and any state after a major interaction (the State Screenshots block in the script template above handles this).
+
+**Visual checklist — fail the run if any item is `no`:**
+- [ ] No unintended scrollbars
+- [ ] No text ending in `…` that shouldn't be
+- [ ] Hero elements fully visible (not sliced)
+- [ ] Right-edge controls fully visible
+- [ ] No overlapping rows
+- [ ] Content uses the available width — no asymmetric dead zones (e.g. content pinned to one edge leaving empty space on the other)
+- [ ] Spacing intentional — not cramped, not unintentionally vast
+- [ ] Theming matches the user's ask (Light/Dark/HighContrast if relevant)
+- [ ] Focus/hover/error states render if tested
+
+If the checklist fails, it's a bug — fix before declaring done. Window too small → grow per `winui-design` Step 4.
+
 ### Step 4: Fix and Rerun (if the user asked for it)
 
 If tests fail: