Add WinUI layout skill

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -26,6 +26,7 @@ body:
         - "skill: winui (agent)"
         - "skill: winui-dev-workflow"
         - "skill: winui-design"
+        - "skill: winui-layout"
         - "skill: winui-code-review"
         - "skill: winui-ui-testing"
         - "skill: winui-packaging"

.github/skills/pr-review/dimensions/docs-and-manifests.md

@@ -12,7 +12,7 @@ you with the `explore` agent type by default.
 The repo's user-facing surface and its install/discovery metadata.
 When code or skills change, these need to keep up:
 
-- `README.md` — top-level pitch, install instructions, the "8 skills"
+- `README.md` — top-level pitch, install instructions, the skills
   table, the "in-repo tools" table.
 - `plugins/winui/plugin.json` — Copilot/Claude/Codex plugin manifest
   (name, description, version, agents, skills).
@@ -36,7 +36,7 @@ When code or skills change, these need to keep up:
 ### New / renamed / removed skill
 
 - **New skill added under `plugins/winui/skills/<new>/`** without a
-  matching row in `README.md`'s "eight skills" table → **high**.
+  matching row in `README.md`'s skills table → **high**.
 - **Skill renamed.** `plugins/winui/agents/winui-dev.agent.md`
   references skills by name (e.g. "Load the `winui-dev-workflow`
   skill"). Renames must update every mention in the agent file

.github/skills/pr-review/dimensions/skill-content.md

@@ -11,7 +11,7 @@ field.
 
 This dimension reviews **prose changes** to:
 
-- `plugins/winui/skills/<name>/SKILL.md` (the 8 shipped skills)
+- `plugins/winui/skills/<name>/SKILL.md` (the shipped skills)
 - `plugins/winui/skills/<name>/references/*.md` (deep-dive references
   loaded on demand)
 - `plugins/winui/agents/winui-dev.agent.md` (the orchestrator agent
@@ -70,7 +70,7 @@ priors. Every line of prose must pull its weight.
 
 ### Structure consistency
 
-- New skills should match the structure of the 8 existing ones:
+- New skills should match the structure of the existing shipped skills:
   frontmatter → "When to Use" → numbered/headed sections of
   guidance → optional "References" pointer to `references/`. Major
   deviations from this pattern reduce skill discoverability for the

CHANGELOG.md

@@ -23,6 +23,9 @@ The `version-bump` and `changelog-entry` CI jobs enforce this.
 
 ### Added
 
+- `winui-layout` skill for page silhouettes, responsive breakpoints,
+  adaptive XAML, title bar layout, layout panels, and initial window sizing.
+
 ### Changed
 
 ### Fixed
@@ -52,7 +55,7 @@ release process was introduced. Future releases will list per-PR changes here.
 
 ### Added
 
-- Initial public preview of the `winui` plugin: `winui-dev` agent and the eight
+- Initial public preview of the `winui` plugin: `winui-dev` agent and the original eight
   skills (`winui-dev-workflow`, `winui-design`, `winui-code-review`,
   `winui-ui-testing`, `winui-packaging`, `winui-wpf-migration`,
   `winui-session-report`, `winui-setup`).

README.md

@@ -106,7 +106,7 @@ The result: you ask `copilot -p "create a WinUI 3 photo viewer with thumbnails a
 .github/plugin/        Marketplace manifest (marketplace.json)
 plugins/winui/         Copilot CLI plugin manifest + agent + skill files
   agents/winui-dev/    The orchestrator agent
-  skills/              The eight skills (see table below)
+  skills/              The nine skills (see table below)
 src/tools/             Source for the in-repo tools shipped with the skills
   winmd-cli/           Native-AOT WinRT/.NET metadata indexer (winmd.exe)
   winui-search/        Native-AOT search over WinUI Gallery + Toolkit (winui-search.exe)
@@ -118,14 +118,15 @@ scripts/               Helper scripts (see scripts/build-tools.ps1)
 
 A focused agent for WinUI 3 / Windows App SDK / XAML / C# work. Use it for new apps, adding features, converting from WPF/Electron/web, or fixing bugs. It pulls in the skills below as needed.
 
-### The eight skills
+### The nine skills
 
-Each skill is a focused, self-contained playbook. The agent loads `winui-design` and `winui-dev-workflow` by default — those cover most "build me a WinUI 3 app" requests end-to-end. You opt into the others when you want them, including `winui-setup` for one-time machine prep.
+Each skill is a focused, self-contained playbook. The agent loads `winui-design` and `winui-dev-workflow` by default — those cover most "build me a WinUI 3 app" requests end-to-end; `winui-design` routes deeper page layout work to `winui-layout` when needed. You opt into the others when you want them, including `winui-setup` for one-time machine prep.
 
 | Skill | What it does |
 |---|---|
 | **`winui-dev-workflow`** | Build and run workflow — project creation from templates, the `BuildAndRun.ps1` helper, `winapp run`, error diagnosis, prerequisites. Use when building, running, or fixing build errors. |
 | **`winui-design`** | UI design and XAML correctness — layout planning, control selection, Fluent Design, theming (Light/Dark/HighContrast), typography, spacing, brushes, accessibility, data-binding review. Bundles `winui-search.exe` for grounded control lookup against the WinUI Gallery + Community Toolkit catalogue. |
+| **`winui-layout`** | Page layout and responsive design — app silhouettes, breakpoints, adaptive XAML, title bar composition, content spacing, layout panels, and initial window sizing based on Microsoft Learn layout guidance. |
 | **`winui-code-review`** | Code-quality review before committing — MVVM compliance, `x:Bind` correctness, accessibility, theming, security, performance. Catches what the compiler and UI tests won't. |
 | **`winui-ui-testing`** | Automated UI testing — generates a batch test script, runs all tests in one pass, reads results. Covers element assertions, interactions, value checks (TextBox, ComboBox, ToggleSwitch), file pickers, flyouts, dialogs, persistence, accessibility audits. |
 | **`winui-packaging`** | MSIX packaging, code signing, and distribution — release builds, certificate generation (`winapp cert generate`), trust, signing (`winapp sign`), self-contained deployment, GitHub Actions CI/CD, and Microsoft Store submission. |

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

@@ -35,51 +35,15 @@ description: "WinUI 3 UI design and XAML correctness — layout planning, contro
 **Feedback:** Blocking decision → `ContentDialog`; contextual action → `Flyout`/`MenuFlyout`; onboarding → `TeachingTip`; inline status → `InfoBar`; system notification → `AppNotification`.
 
 #### 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
+For app silhouette, responsive breakpoints, adaptive XAML, title bar composition, panel choice, and initial window size, use `winui-layout` before writing page XAML. Return here for control lookup, theming, typography, brushes, accessibility, and binding correctness.
 
-#### 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.
+Minimum layout defaults: content fills the window, ordinary pages use a `Grid` skeleton, `StackPanel` is local-only, and floating cards on empty backgrounds need a strong product reason.
 
-`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)));
-    }
-}
-```
+#### Step 4: Size the Window to the App
 
-`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.
+Use `winui-layout` to derive the initial window size from the page layout. WinUI 3 has no `SizeToContent`; do not fake it by setting `Width` or `Height` on the root element because that clips content instead of resizing the app window.
 
-If the user asks for UI validation, see `winui-ui-testing` Step 3.5 to verify the rubric against the visual checklist.
+If the user asks for UI validation, see `winui-ui-testing` Step 3.5 to verify layout and window fit against the visual checklist.
 
 #### Step 5: Design Anti-Patterns
 | ❌ Don't | ✅ Do Instead |
@@ -219,3 +183,4 @@ ToolTipService.SetToolTip(btn, "Save the current document");
 | `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 |
+| Sibling skill: `winui-layout` | Page silhouette, responsive breakpoints, title bar layout, layout panels, content spacing, and initial window sizing |

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

@@ -0,0 +1,116 @@
+---
+name: winui-layout
+description: "Use when designing or reviewing WinUI 3 page layout, app silhouette, responsive breakpoints, adaptive XAML, title bar composition, content spacing, layout panels, initial window size, or fixing pages that feel cramped, over-carded, fixed-size, clipped, or waste space across small, medium, and large window widths."
+---
+
+# WinUI Layout
+
+## Overview
+
+Shape the app window before styling the controls. Use this skill to choose the page silhouette, responsive states, title bar layout, layout panels, and initial window size from Microsoft Learn layout guidance.
+
+Keep this skill focused on layout. Use `winui-design` for control selection, theme resources, typography styles, brushes, data binding, and accessibility; use `winui-ui-testing` for runtime UI automation and screenshot validation; use `winui-code-review` for pre-commit quality review.
+
+## When to Use
+
+Use this skill when the task involves:
+
+- Designing a new WinUI page shell, dashboard, settings surface, editor, media view, or multi-pane utility.
+- Fixing a page that wastes space, clips content, overuses cards, or feels cramped at different window widths.
+- Choosing between top navigation, left navigation, menu bar, or `TabView`.
+- Defining small, medium, and large responsive states.
+- Selecting layout panels or replacing fixed-size `Canvas`/whole-page `StackPanel` layouts.
+- Integrating title bar content such as search, account UI, app icon, or document tabs.
+- Deriving an initial window size from the actual layout.
+
+Do not use this skill for isolated control selection, brush names, binding syntax, or post-build code review; use the sibling skills named in the overview.
+
+## Layout Workflow
+
+### 1. Pick the app silhouette
+
+Choose one primary page shell before choosing individual controls:
+
+| App shape | Use | Avoid |
+|---|---|---|
+| Top navigation | Media, gallery, or document-style apps that need vertical space | Deep section trees |
+| Menu bar | Dense editor or utility surfaces where content is the main task | App-wide navigation with many destinations |
+| Left navigation | Settings, dashboards, and multi-section tools | Single-purpose pages |
+| TabView | Documents, terminals, code editors, or multi-session work | Static app sections that are not documents/sessions |
+
+Do not mix two primary navigation systems unless the product model really has two independent axes, such as app sections plus document tabs.
+
+### 2. Define responsive states
+
+Design against the app window width in effective pixels, not the physical monitor or device class.
+
+| State | Width | Layout decision |
+|---|---:|---|
+| Small | under 640 epx | Single-column content, collapsed navigation, minimum metadata |
+| Medium | 641-1007 epx | Compact side-by-side regions only when the task benefits |
+| Large | 1008 epx and wider | Show persistent navigation, detail panes, richer metadata, or extra columns |
+
+For each state, specify what repositions, resizes, reflows, appears, disappears, or changes architecture. If the change is only cosmetic, do not add a breakpoint.
+
+### 3. Choose layout panels intentionally
+
+Use panels for their sizing behavior, not just because they are convenient:
+
+| Panel | Use for | Watch for |
+|---|---|---|
+| `Grid` | Page skeletons, resizable rows/columns, master-detail layouts | Prefer `Auto`, `*`, `MinWidth`, and `MaxWidth` over fixed page sizes |
+| `RelativePanel` | Repositioning related elements across visual states | Do not use it when a simple grid row/column is clearer |
+| `StackPanel` | Small local stacks inside a section | Do not use one StackPanel as the whole page shell |
+| `VariableSizedWrapGrid` | Wrapping tiles or variable grid items | Set item sizing deliberately |
+| `Canvas` | Graphics, diagrams, or small static regions | Do not use it for ordinary app layout |
+
+Use `VisualStateManager` and `AdaptiveTrigger` for major layout changes. Use `Visibility` or `x:Load` when a state hides expensive or secondary UI.
+
+### 4. Set content rhythm
+
+Make content fill the window with meaningful margins; do not center a lone card on an empty background unless the whole app is a narrow dialog-like utility. Keep spacing semantic:
+
+- 8 epx: closely related controls or a button and flyout.
+- 12 epx: control-to-label or compact content-region spacing.
+- 16 epx: text inside a surface edge, or a control next to an expander action.
+- 48 epx: nested expander content indentation.
+- 56 epx: large media or highly cohesive content margins, not dense tools.
+
+For dense developer tools, prefer compact margins and stable scanning. For media or gallery surfaces, allow larger margins when they strengthen the content.
+
+### 5. Integrate the title bar
+
+Use the platform title bar model unless there is a specific reason to customize it.
+
+- Standard title bars are 32 px high.
+- Use 48 px when the title bar contains global search or account/person UI.
+- Keep empty and non-interactive title-bar regions draggable.
+- Preserve system menu behavior on icon/right-click/press-and-hold regions.
+- Keep caption buttons visible and separate from app commands.
+- If tabs are the main app element, integrate `TabView` with title-bar space while preserving caption button placement.
+
+### 6. Derive the initial window size
+
+WinUI 3 does not size the main window to content automatically. Pick an initial size from the layout:
+
+- Width: widest useful row plus horizontal page padding, rounded up.
+- Height: title bar plus visible rows, spacing, and vertical page padding, rounded up.
+- Small utilities can be narrow; multi-pane tools usually need a wider initial window; document/canvas apps should start wide enough to show the primary work area.
+- If you call `AppWindow.Resize`, convert DIPs to physical pixels for the active monitor.
+
+After implementing, verify at small, medium, and large widths. If UI validation is requested, use `winui-ui-testing`; if visual fit is suspect, capture screenshots before claiming the layout is complete.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Fixed `Width`/`Height` on a page root | Use `Grid`, `Auto`, `*`, and min/max constraints |
+| One whole-page `StackPanel` | Use a page-level `Grid` and local stacks only inside sections |
+| `Canvas` for form or dashboard layout | Use `Grid` or `RelativePanel` |
+| Desktop-only design | Define small, medium, and large window states |
+| Extra cards inside page sections | Let sections fill the page; reserve cards for repeated items or framed tools |
+| Breakpoints by device name | Trigger on available window width |
+
+## References
+
+Read `references/microsoft-layout-guidelines.md` when you need the source-backed Microsoft Learn layout guidance, breakpoint definitions, title-bar rules, panel behavior, or examples of how to map the guidance into XAML layout decisions.