Trimming design skill#96
Merged
Merged
Conversation
…tion 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>
…ence
Grafted back from public Microsoft Learn sources after audit identified
high-value losses worth restoring:
SKILL.md:
- App-shape anchors table with Reference-App column (Settings, Terminal,
File Explorer, Dev Home, Calculator)
- x:Bind static-method pattern for bool->Visibility, with explicit
'never use Converter={x:Null}' runtime-crash warning
- Anti-patterns table replaces bullet list (13 rows, contrastive)
New reference:
- references/brushes-and-icons.md (12 KB): brush catalogue + IconElement
taxonomy, sourced from learn.microsoft.com xaml-theme-resources and
design/style/icons pages
Total skill now 43.7 KB (vs 51.5 KB original = 15% smaller, vs 29 KB
after the initial trim = + grafted high-value content).
Verified zero prose overlap with windows-xaml plugin via 8-gram shingle
scan (only shared content is learn.microsoft.com URL fragments).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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>
Feedback from real usage: agent-generated WinUI apps all look 'samey' — same NavigationView Left + system grey Mica + default accent + grey cards, regardless of app purpose. Diagnosed as ~60% skill bias (anchors exclusively to Microsoft first-party apps, bans the moves that create identity) and ~40% platform (Fluent is consistency by design). Minimal middle-ground intervention, ~800 bytes: 1. Anchors table: added one row (media/canvas/hero — no NavView) and non-Microsoft reference apps in every row (Slack, VS Code, Outlook, GitHub Desktop, Spotify, Clipchamp). Three of six rows still anchor on NavigationView — this isn't anti-NavView, just not exclusively. 2. New short section 'Before reaching for defaults — one identity beat': forces ONE backdrop+accent decision before coding. Names overriding SystemAccentColor and tinted DesktopAcrylicBackdrop as on-pattern (Microsoft's own apps do this). Explicit permission to skip for utilities so we don't over-engineer brand identity for a calculator. 3. Anti-patterns table: replaced first two rows with two new ones that bless silhouette variety and brand customisation. Doesn't add new rows, doesn't remove the substantive bans below. No new files, no new references, no worked code (agent knows syntax once told the pattern is on-pattern — the unlock is permission). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ples
SKILL.md contradicted itself: a whole section tells the agent to
front-load winui-search.exe lookups *before* writing XAML, then handed
them a baked-in NavigationView + SettingsCard skeleton that pre-empted
the search. That skeleton was the proximate cause of the 'every app
looks like Settings' feedback — it's always-loaded into context.
Verified the tool returns rich samples for both ('gallery-navigationview-1'
for the shell + 'toolkit-settingsexpander-*' for the cards), so the
skeleton is fully redundant.
Skill teaches decisions; tool provides samples. Restore that boundary.
PaneDisplayMode guidance dropped with the snippet — also redundant with
gallery-navigationview-1's full sample which shows all four modes.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…c guidance
Full audit of remaining over-specific examples after the sidebar-skeleton
removal. Seven biasing items found, six fixed (one was acceptable API
description in brushes-and-icons.md and was left alone).
SKILL.md:
- Mica wiring section: dropped 'MicaBackdrop { Kind = Base }' headline code
(it's the default — showing it as 'the example' undoes the identity beat
two paragraphs up). Replaced with a 3-option bullet list matching the
identity-beat choices: Mica, tinted Acrylic, no backdrop.
- Window-sizing DPI snippet: replaced literal '460 * scale, 860 * scale'
(a portrait sidebar-shaped utility window) with widthDip/heightDip
placeholders so the agent derives values from the rubric.
- Anti-pattern 'Centered floating card on empty background': re-scoped
to the actual bug (tiny island on oversized window). The previous
framing banned hero/welcome/empty-state surfaces, which are legitimate.
- Anti-pattern '50/50 split → fixed sidebar 280-360 px': removed the
Shell-prescriptive correction. Now reads 'stable size for structural
pane, flexible for content — only if a structural pane is part of the
silhouette at all'.
references/layout-review.md:
- Page-planning silhouette list: aligned with SKILL.md anchors table
(added canvas-hero, dense-grid; removed redundant 'tabs', 'menu+command').
- DELETED 'Sidebar / content sizing rules of thumb' section entirely.
It was Shell-specific (OpenPaneLength, settings cards, 'matches Windows
Settings') sitting in a generic responsive-review reference. Same kind
of bias as the deleted sidebar skeleton; winui-search owns those values.
references/theme-accessibility.md:
- ThemeDictionary example renamed 'CardBackgroundBrush' to 'AppSurfaceBrush'
so the example doesn't quietly assume cards are the surface vocabulary.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Validated all 5 landmines against authoritative sources (Microsoft Learn, the in-repo WinUI analyzer's own RULES.md, and a built-and-run WinUI 3 test app). Four needed corrections:
* TextBox UpdateSourceTrigger: dropped the 'silently breaks UI Automation set-value' framing. WinUI 3 TextBox does not implement IValueProvider (uses ITextProvider2). Replaced with the real concern: VM is stale until LostFocus, breaking UIA keyboard-simulation tests (WinAppDriver SendKeys, etc.).
* Attached-property initializer: changed 'compiles, does nothing' to the truth — does not compile (CS0117). 'Button' has no 'AutomationProperties' instance member; it's a static accessor class. This matches the in-repo WUI2030 analyzer rule, which already says 'Doesn't compile' — SKILL.md was internally inconsistent.
* Converter={x:Null}: clarified this hits {x:Bind} specifically (compiles, then LookupConverter(\\\) returns null, NullReferenceException at activation). Added the actual error string from WUI2012 so agents can recognize it in crash logs.
* Acrylic + ThemeShadow: BackgroundSizing=InnerBorderEdge IS the default — old text implied you had to add it. Translation=0,0,32 is the recommended popup elevation, not a hard requirement (tooltips use 16, dialogs use 128). Removed the '>=12 px parent padding' rule — fabricated, not in any MS doc; replaced with the real non-popup gotcha (must populate ThemeShadow.Receivers).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…lay / Input) Benchmark on this branch showed agents reaching for CommunityToolkit DataGrid for tabular scenarios. Root cause: the clean-room rewrite dropped the three short 'requirement -> platform control' mapping sentences that main branch had, so nothing in SKILL.md was steering agents away from cross-framework instincts (WPF DataGrid, web <select>, HTML date input). Re-add them as a compact 'Reach-for-this control map' section with a tighter framing line. The tabular bullet now explicitly calls out the anti-pattern by package name (CommunityToolkit.WinUI.Controls.DataGrid) and the concrete reason agents should not reach for it (column bindings can't use x:Bind), and redirects to ListView + Grid-based ItemTemplate + header Grid above. Closes the regression vs main without restoring the full deleted control-selection.md reference. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…ive-action rule, search discoverability) Three surgical additions based on a comparative benchmark run against main: * Feedback bullet in the Reach-for-this control map (ContentDialog / Flyout / TeachingTip / InfoBar / AppNotification). Mirrors main; addresses ContentDialog and InfoBar regressions observed on this branch where agents were not picking the right feedback surface. * Anti-patterns row for destructive actions without confirmation. This is a pre-existing gap on BOTH branches — the benchmark's 'delete with confirmation dialog' requirement was failing 4/4 trials on main and nm alike. Net new improvement, not a regression fix. * One sentence after the winui-search quick-start naming the integration-pattern categories the tool covers (file pickers, Share, JumpList, drag-drop, app lifecycle, dialogs) and stating the don't-interleave rule explicitly. Agents were burning extra tool calls rediscovering scope of the search tool. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Test branch for benchmark experiment: does the 'Before reaching for defaults' section produce any visible difference in generated app identity? Compare against nm/cleanup-design-skill (control) and nm/exp-push-identity (stronger prescription). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
niels9001
reviewed
May 27, 2026
niels9001
approved these changes
May 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.