commit 07c63cb56511a7287bbdc358a72f03c05fe18cfd
Author: QiuSW <105186638@qq.com>
Date:   Sat Jul 18 17:32:02 2026 +0800

    Add English Windows UI UX design skill

diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..0dc7aaa
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: win-ui-ux-design
+description: Design, review, and implement professional Windows desktop UI/UX for WinUI 3, Windows App SDK, XAML, Fluent Design, and Windows-targeted Qt for Python applications using PySide or PyQt. Use when a task involves Windows desktop app shells or screens, Windows 桌面端界面, PySide6, PyQt6, PySide2, PyQt5, Qt Widgets, QML, navigation and windowing, title bars, NavigationView or framework-equivalent control selection, responsive XAML or Qt layouts, theme resources, QPalette or QSS, Mica or Acrylic, keyboard/mouse/touch interaction, accessibility, design-system specifications, UI audits, or translating designs into WinUI 3, PySide, or PyQt code.
+---
+
+# Windows Desktop UI/UX Design
+
+Design for Windows as a keyboard-and-pointer-first, resizable, high-density desktop environment that may also receive touch and pen input. Prefer familiar platform behavior over ornamental novelty.
+
+## Follow the core rules
+
+- Optimize the user's task flow before styling individual controls.
+- Prefer WinUI controls, system resources, and built-in interaction behavior before creating custom UI.
+- Treat keyboard, pointer, touch, screen reader, scaling, theme, and high contrast as one experience rather than later adaptations.
+- Specify every meaningful state: default, hover, pressed, focus, selected, disabled, loading, empty, error, offline or unavailable, success, and undo when relevant.
+- Use semantic tokens and theme resources. Never encode meaning with color alone or assume the light palette works in dark mode.
+- Keep density appropriate for desktop work. Do not enlarge mobile patterns or hide routine commands behind touch-only gestures.
+- Gate every API, control, and Toolkit recommendation by the project's Windows App SDK version, target OS, packaging model, and dependencies.
+- Distinguish WinUI 3 (`Microsoft.UI.Xaml`) from UWP/WinUI 2 (`Windows.UI.Xaml`). Never copy APIs across them without verification.
+
+## Run the workflow
+
+### 1. Establish constraints
+
+Inspect the project before proposing implementation details. Determine:
+
+- framework and exact package versions;
+- minimum Windows version and packaged or unpackaged deployment;
+- primary tasks, audience, localization, data density, and accessibility needs;
+- expected window sizes, multi-window behavior, and resize/snap scenarios;
+- primary input modes and whether touch optimization is required;
+- brand constraints, light/dark behavior, and existing design tokens.
+
+If information is missing, state conservative assumptions and keep version-sensitive recommendations conditional.
+
+### 2. Model the experience
+
+Define the primary jobs, information hierarchy, window map, navigation model, and command surfaces. Keep top-level navigation shallow. Decide which work belongs in the main window, a secondary window, an inline surface, a flyout, or a modal dialog.
+
+Describe the happy path and recovery paths before producing mockups or XAML. Preserve user context across navigation, resize, refresh, and errors.
+
+### 3. Define the visual system
+
+Create a small semantic system for type, spacing, geometry, color, elevation, material, icons, and motion. Use Windows defaults unless the brand requires a deliberate deviation. Read [windows-foundations.md](references/windows-foundations.md) for current Fluent principles, responsive breakpoints, theme, material, and motion guidance.
+
+### 4. Map intent to controls and patterns
+
+Select controls by interaction semantics, not by appearance or arbitrary item-count thresholds. Reuse commands across menus, toolbars, context menus, and accelerators. Read [controls-and-patterns.md](references/controls-and-patterns.md) before choosing navigation, collection, form, settings, feedback, or data-table patterns.
+
+### 5. Specify interaction and accessibility
+
+Document focus order, arrow-key behavior, access keys, accelerators, pointer affordances, context menus, touch targets, drag alternatives, accessible names, announcements, contrast, and scaling. Read [input-accessibility.md](references/input-accessibility.md) for the required interaction and accessibility baseline.
+
+### 6. Engineer and validate
+
+When implementation is requested, follow the existing architecture and centralize tokens, commands, and state. Preserve virtualization and avoid synchronous work on the UI thread. Read [engineering-validation.md](references/engineering-validation.md) for version gates, implementation practices, performance checks, and the test matrix.
+
+Validate the result at realistic compact, medium, and wide window widths rather than only at a full-screen monitor resolution.
+
+## Produce decision-ready output
+
+For a new design, provide:
+
+1. assumptions and target scenarios;
+2. information architecture and window/navigation model;
+3. annotated layout with responsive behavior;
+4. control and command mapping;
+5. semantic visual tokens;
+6. interaction and state matrix;
+7. accessibility requirements;
+8. implementation notes and acceptance checks.
+
+For a review, lead with findings ordered by severity. For each finding, identify the affected screen or control, user impact, violated Windows convention, and concrete correction. Separate correctness and accessibility defects from subjective polish suggestions.
+
+For implementation, change only the requested scope, reuse the project's patterns, build or run relevant checks, and report any API/version assumptions that remain unverified.
+
+## Reject common failure modes
+
+- Do not present obsolete UWP or archived Toolkit APIs as current WinUI 3 guidance.
+- Do not recommend `ComboBox` for multiple selection; it does not support it.
+- Do not assume the archived Windows Community Toolkit `DataGrid` is available in current WinUI 3 projects.
+- Do not use emoji as structural interface icons; use platform glyphs or a consistent vector icon set.
+- Do not force Acrylic onto every surface. Use materials to express hierarchy and provide readable solid fallbacks.
+- Do not require `AutomationProperties.Name` where a standard control already exposes an accurate accessible name; add explicit names when semantics are otherwise missing.
+- Do not confirm every deletion by default. Prefer undo for frequent, recoverable actions and reserve modal confirmation for costly or irreversible consequences.
+- Do not hard-code one window size, theme, DPI, locale, or input method as the design baseline.
diff --git a/agents/openai.yaml b/agents/openai.yaml
new file mode 100644
index 0000000..9896c77
--- /dev/null
+++ b/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Windows UI/UX Design"
+  short_description: "设计、评审并实现专业的 Windows 桌面端体验"
+  default_prompt: "Use $win-ui-ux-design to design and review a Windows desktop app experience."
diff --git a/references/controls-and-patterns.md b/references/controls-and-patterns.md
new file mode 100644
index 0000000..bbc290f
--- /dev/null
+++ b/references/controls-and-patterns.md
@@ -0,0 +1,163 @@
+# WinUI controls and desktop patterns
+
+## Contents
+
+1. Selection method
+2. Navigation and window shell
+3. Collections and structured data
+4. Input controls and forms
+5. Commands and menus
+6. Feedback and transient surfaces
+7. Common page patterns
+8. Control review checklist
+9. Official sources
+
+## 1. Selection method
+
+Choose controls by semantics and built-in behavior:
+
+1. Identify whether the user is navigating, selecting, invoking, editing, comparing, or inspecting.
+2. Prefer the control that already implements the expected keyboard, focus, selection, automation, and theme behavior.
+3. Check availability against the exact Windows App SDK or Toolkit version.
+4. Customize styles before templates; replace the control only if its interaction model is wrong.
+5. Record accessibility, localization, performance, maintenance, and licensing costs for third-party controls.
+
+Do not choose a control from a screenshot alone. Two controls can look similar while exposing different semantics to keyboard and assistive technology.
+
+## 2. Navigation and window shell
+
+| Intent | Use | Avoid |
+|---|---|---|
+| Top-level app destinations | `NavigationView` | custom sidebar without Windows navigation behavior |
+| Small set of static peer views | `SelectorBar` or a simple selector appropriate to content | document-style tabs for unrelated destinations |
+| Open documents or closeable workspaces | `TabView` | `NavigationView` items masquerading as documents |
+| Hierarchical location path | `BreadcrumbBar` | concatenated text and separators |
+| Hierarchical data | `TreeView` | recursively nested `ListView` controls |
+| List and selected item | list/details pattern | forcing every detail into a modal |
+
+Keep top-level navigation shallow, stable, and labeled. Select top or left `NavigationView` by content breadth, localization, growth, window width, and command density—not a universal item-count rule. Let `PaneDisplayMode="Auto"` and control thresholds handle common adaptive behavior unless the experience requires deliberate states.
+
+Use `Frame` only when page navigation and a back stack match the experience. Preserve selection, filter, scroll, and unsaved state when navigating back. Do not show a back button if there is nowhere meaningful to go.
+
+For Windows App SDK 1.7 or later, prefer the WinUI `TitleBar` control for a customized title bar and coordinate it with `NavigationView`. On earlier versions, use the supported `Window.ExtendsContentIntoTitleBar` and `Window.SetTitleBar` path. Preserve caption buttons, drag regions, system menu access, active/inactive appearance, and resize behavior.
+
+Use additional windows for genuinely parallel or detachable work, not as a replacement for information hierarchy. Define owner, activation, placement, close behavior, and state synchronization.
+
+## 3. Collections and structured data
+
+| Need | Preferred option | Notes |
+|---|---|---|
+| Text-heavy selectable collection | `ListView` | mature selection, grouping, reorder, and virtualization behavior |
+| Uniform visual tiles | `GridView` | use a virtualizing items panel |
+| Flexible list/grid/custom layouts | `ItemsView` | modern composition with layout switching and built-in selection/accessibility |
+| Low-level custom virtualized layout | `ItemsRepeater` | selection, invocation, focus, and automation may need extra engineering |
+| Hierarchy | `TreeView` | supports single and multiple selection |
+| Simple read-only rows and columns | templated `ListView`/`ItemsView` | provide headers and accessible relationships |
+| Full spreadsheet-like editing | verified maintained table component | validate keyboard, UI Automation, virtualization, sorting, resize, and editing |
+
+Do not decide `ListView` versus a data table from a fixed threshold such as 20 rows. Base the choice on column relationships, comparison, sorting, editing, selection, virtualization, and keyboard navigation.
+
+The Windows Community Toolkit `DataGrid` documentation is archived; it is not a current WCT 8+ WinUI 3 control. For new work, evaluate currently maintained options such as Toolkit Labs `DataTable` or the community `WinUI.TableView`, and explicitly verify their maturity and requirements. Do not silently introduce one.
+
+Keep virtualization enabled for large or unbounded collections. Never replace a virtualizing panel with a generic panel without measuring the result. Provide loading, empty, filtered-empty, partial-data, stale, and load-failure states.
+
+For selection, support Windows conventions: click/tap for a single item, Ctrl for independent selection, Shift for ranges, Space for focused selection where the control supports it, and visible selection independent from keyboard focus.
+
+## 4. Input controls and forms
+
+| Intent | Use | Important distinction |
+|---|---|---|
+| Short or multiline plain text | `TextBox` | use `AcceptsReturn` and suitable wrapping for multiline |
+| Rich formatted editing | `RichEditBox` | do not use for plain multiline text |
+| Numeric value | `NumberBox` | still validate range and domain constraints |
+| Date | `DatePicker` or `CalendarDatePicker` | choose persistent picker versus compact calendar entry |
+| Time | `TimePicker` | respect locale formatting |
+| Immediate on/off setting | `ToggleSwitch` | label the state clearly |
+| Selection in a form or batch list | `CheckBox` | supports checked, unchecked, and optional indeterminate semantics |
+| One visible option from a small set | grouped `RadioButton` controls | use `ComboBox` when space or option count makes scanning worse |
+| One option from a compact list | `ComboBox` | it does not support multiple selection |
+| Multiple options | `ListView`, `ItemsView`, checked list, or purpose-built flyout | keep selected values reviewable |
+| Bounded continuous value | `Slider` | show current value and allow precise keyboard entry when needed |
+| Rating | `RatingControl` | use only for genuine rating semantics |
+
+Place labels where scan order remains clear under narrow widths, text scaling, and localization. Use `AutomationProperties.LabeledBy` when a separate label must be associated with a field. Mark required fields in text, not color alone. Provide constraints before entry, validate at a useful boundary such as blur or submit, and state both the problem and recovery.
+
+Do not disable the primary action without explaining unmet requirements. Preserve user input on validation or network failure. For long forms, define draft, cancel, close, and unsaved-change behavior.
+
+## 5. Commands and menus
+
+Model a command once and expose it through suitable surfaces using `StandardUICommand`, `XamlUICommand`, or the project's `ICommand` pattern.
+
+| Surface | Use |
+|---|---|
+| Primary page command | visible `Button` or `CommandBar` command |
+| Document-centric application menus | `MenuBar` |
+| Object-specific commands | `ContextFlyout`, preferably `CommandBarFlyout` when rich commands help |
+| Extra or low-frequency commands | secondary `CommandBar` commands or overflow menu |
+| Split default/alternate action | `SplitButton` |
+| Menu-only action set | `DropDownButton` or `MenuFlyout` |
+| Power-user path | `KeyboardAccelerator` plus tooltip/menu shortcut text |
+
+Keep critical commands discoverable without hover or gestures. Include relevant contextual commands in a context menu so pointer, keyboard, touch, and assistive technology users have a common route. Use access keys for efficient Alt navigation and accelerators for repeated actions.
+
+Use specific action labels such as “Delete 3 files” rather than “OK”. Keep destructive commands spatially separated and show consequence. Offer undo when the action is common and reversible.
+
+## 6. Feedback and transient surfaces
+
+| Need | Use | Guidance |
+|---|---|---|
+| Inline status, warning, or recoverable error | `InfoBar` | keep visible while action is required; do not assume automatic dismissal |
+| First-use education anchored to UI | `TeachingTip` | show sparingly and never for routine status |
+| Blocking decision or irreversible consequence | `ContentDialog` | ask only when the app cannot safely choose or offer undo |
+| Contextual options or detail | `Flyout` | dismissible and connected to its source |
+| Determinate work | `ProgressBar` | report meaningful progress |
+| Indeterminate short wait | `ProgressRing` | keep surrounding context stable |
+| Long/background work | in-page progress plus cancel/background affordance | do not trap users in a spinner |
+
+For frequent destructive actions, prefer immediate completion plus undo over repeated confirmation. For truly destructive dialogs, make the title state the decision and use explicit button verbs.
+
+Every async surface needs a success, failure, timeout, retry or alternate path, and cancellation strategy when cancellation is meaningful. Avoid white screens and layout jumps; retain the previous content or use a shape-matched placeholder.
+
+## 7. Common page patterns
+
+### Application shell
+
+Use title bar, top-level navigation, page header, contextual commands, and a content frame or presenter. Keep title-bar drag regions separate from interactive navigation and search controls.
+
+### Settings
+
+Use Windows Community Toolkit `SettingsCard` and `SettingsExpander` only after verifying the installed Toolkit package. Group by user intent, add descriptions for non-obvious consequences, and make reversible preferences apply immediately. Use Apply, restart, or confirmation only when a change is expensive, delayed, security-sensitive, or not safely reversible.
+
+### List/details
+
+At wide widths, show list and details together. At compact widths, navigate between them while preserving list selection, scroll, filter, and keyboard focus. Define what happens when the selected item is deleted, filtered out, or fails to load.
+
+### Form or editor
+
+Use a predictable scan path, keep related controls together, align actions consistently, and reserve space for validation. Make save state explicit: saved, saving, unsaved, conflict, offline, or failed. Provide undo/redo for document-like work.
+
+### Empty and error states
+
+State what happened, why when known, and what the user can do next. Tailor empty states: first-use empty, filtered empty, permission denied, disconnected, and failed loading are different problems.
+
+## 8. Control review checklist
+
+- [ ] Each control matches the user's intent and exposes correct semantics.
+- [ ] All APIs and dependencies exist in the project's versions.
+- [ ] Navigation, selection, focus, and back behavior are defined.
+- [ ] Contextual commands have a non-hover route.
+- [ ] Collection virtualization and keyboard behavior are preserved.
+- [ ] Forms retain input and provide actionable validation.
+- [ ] Dialogs are limited to genuinely blocking decisions.
+- [ ] Loading, empty, error, timeout, cancellation, and undo states are handled.
+
+## 9. Official sources
+
+- [Controls for Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
+- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
+- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
+- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
+- [Commanding](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
+- [Dialogs and flyouts](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
+- [App settings guidelines](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
+- [Archived WCT DataGrid status](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)
diff --git a/references/engineering-validation.md b/references/engineering-validation.md
new file mode 100644
index 0000000..009cddc
--- /dev/null
+++ b/references/engineering-validation.md
@@ -0,0 +1,143 @@
+# WinUI engineering and validation
+
+## Contents
+
+1. Version and dependency gates
+2. XAML and state architecture
+3. Windowing and responsive implementation
+4. Performance and async behavior
+5. Implementation review
+6. Release test matrix
+7. Severity model
+8. Official sources
+
+## 1. Version and dependency gates
+
+Before generating XAML or C#:
+
+1. Read the project file, central package props, target framework, target/min Windows versions, and installed packages.
+2. Identify the Windows App SDK and Windows Community Toolkit versions exactly.
+3. Check whether the project is packaged or unpackaged and whether it uses single-project MSIX.
+4. Verify the proposed API in current Microsoft documentation and, for controls, the WinUI 3 Gallery.
+5. Record minimum-version and fallback behavior in the recommendation.
+
+Use `Microsoft.UI.Xaml` for WinUI 3. Treat examples using `Windows.UI.Xaml`, WinUI 2 Gallery, or UWP-specific APIs as migration inputs, not copy-ready code.
+
+Examples of version-sensitive guidance:
+
+- the WinUI `TitleBar` control requires Windows App SDK 1.7 or later;
+- `SystemBackdropElement` requires Windows App SDK 1.6.3 or later;
+- Mica requires Windows 11 and falls back to a solid theme surface on Windows 10;
+- Windows Community Toolkit `DataGrid` is archived and not a WCT 8+ WinUI 3 control.
+
+For any third-party control, document package, version, license, maintenance status, supported Windows versions, theme/high-contrast behavior, UI Automation support, keyboard model, localization, virtualization, and escape plan.
+
+## 2. XAML and state architecture
+
+- Follow the project's MVVM or code-behind conventions; do not introduce a second architecture for one screen.
+- Represent user actions as reusable commands when the same action appears in buttons, menus, context menus, and accelerators.
+- Keep view state explicit: idle, loading, content, empty, filtered empty, error, offline/stale, permission denied, and partial result as applicable.
+- Centralize semantic colors, type styles, spacing, geometry, icon sizes, and motion in resource dictionaries.
+- Use `ThemeResource` for values that must change while the app is running and `StaticResource` only when runtime theme updates are not required.
+- Put light, dark, and high-contrast mappings in theme dictionaries when custom tokens are necessary.
+- Prefer styles and composition over copying full control templates. A custom template inherits responsibility for every visual and accessibility state.
+- Use `x:Bind` or the project's established binding approach consistently. Make binding mode and update timing explicit for editable values.
+- Use Grid and flexible sizing for structured layouts; avoid deep nested panels and fixed sizes that break localization or text scaling.
+- Keep visual order aligned with reading and tab order.
+
+Do not write UI-thread dispatching as a substitute for sound async ownership. Marshal only the final state update that truly requires the UI thread and ensure the view is still alive.
+
+## 3. Windowing and responsive implementation
+
+### Title bar
+
+Keep system caption buttons and the system menu. Define a drag region along the top edge, exclude interactive children from drag regions, and test active/inactive appearance. Verify maximize, restore, resize, Snap Layouts, touch, right-click system menu, and high contrast.
+
+Prefer the platform `TitleBar` control when the project version supports it. When using `NavigationView` with that control, let one component own back and pane-toggle behavior rather than showing duplicate buttons.
+
+### Responsive layout
+
+Start with a safe compact layout and add wider visual states. Use effective window/content width. Test each transition in both directions and preserve:
+
+- selection and keyboard focus;
+- scroll position and expanded state;
+- input and validation state;
+- command availability;
+- accessible reading order.
+
+Avoid replacing the whole visual tree on every resize if a reflow or reposition is sufficient. Debounce expensive resize-driven work and never rebuild data collections solely because the window crossed a breakpoint.
+
+### Multi-window
+
+Define ownership, activation, persisted placement, minimum size, close confirmation, and shared data lifetime. Ensure commands act on the active document/window context and that dialogs have the correct XamlRoot/owner.
+
+## 4. Performance and async behavior
+
+- Keep collection virtualization enabled and measure with realistic data, images, templates, and grouping.
+- Prefer `ListView`, `GridView`, or `ItemsView` behavior before low-level `ItemsRepeater` customization.
+- Decode images near their rendered size, avoid loading full-resolution assets for thumbnails, and cancel work for recycled items.
+- Avoid synchronous file, network, database, or expensive serialization work on the UI thread.
+- Make async commands idempotent or prevent duplicate invocation while work is active.
+- Support cancellation for long operations and ignore stale results after navigation, search-query changes, or window close.
+- Show immediate command feedback. Delay large skeleton/progress transitions just enough to avoid flicker for near-instant work, while never leaving the UI apparently frozen.
+- Keep previous usable content visible during refresh when safe; distinguish refresh from first load.
+- Animate opacity and transforms where possible; avoid layout-heavy animation across large trees.
+- Defer expensive secondary content until requested, but do not lazy-load controls required for keyboard order or core task comprehension without a plan.
+- Measure startup, navigation, resize, input latency, scroll smoothness, memory growth, and recovery from device/theme changes.
+
+## 5. Implementation review
+
+Check correctness before visual polish:
+
+- [ ] Namespace, APIs, package versions, and minimum OS are valid.
+- [ ] The project builds without introducing warnings in the changed scope.
+- [ ] Commands cannot double-submit and failures preserve user work.
+- [ ] Every data surface has loading, empty, error, and retry behavior as needed.
+- [ ] Virtualization, recycling, and cancellation work with production-scale data.
+- [ ] Theme resources update at runtime and custom tokens cover high contrast.
+- [ ] Layout survives compact width, long strings, text scaling, and display scaling.
+- [ ] Focus, selection, accessible names, roles, states, and announcements are correct.
+- [ ] Caption controls, drag regions, dialogs, and multi-window ownership behave correctly.
+- [ ] Destructive actions use undo or confirmation proportional to consequence.
+
+## 6. Release test matrix
+
+Test representative combinations rather than one happy-path machine:
+
+| Dimension | Minimum coverage |
+|---|---|
+| Windows | minimum supported OS plus current Windows 11 |
+| Window | supported minimum, small `<=640` epx, medium `641–1007`, large `>=1008`, snapped, maximized |
+| Scale | common 100%, 125%, 150%, 200% display scales and monitor transitions |
+| Text | default and increased Windows text size |
+| Theme | light, dark, high contrast; transparency on and off |
+| Input | keyboard only, mouse, touch/pen when claimed |
+| Assistive tech | Narrator, Magnifier, Accessibility Insights/Inspect |
+| Content | empty, one item, realistic data, very large data, long localized strings, failures |
+| Environment | slow storage/network, offline, permission denied, RDP or material fallback where relevant |
+| Lifecycle | suspend/close if applicable, reopen, upgrade, secondary-window close, crash-safe data recovery |
+
+Automate stable checks, but keep human review for Narrator flow, focus visibility, touch comfort, motion, wording, hierarchy, and perceived responsiveness.
+
+## 7. Severity model
+
+Use this order when reviewing a design or implementation:
+
+| Severity | Definition | Examples |
+|---|---|---|
+| Blocker | Prevents a primary task, excludes an input/accessibility mode, loses data, or uses an unavailable API | keyboard trap, clipped save button, archived control assumed present |
+| Major | Causes frequent error, disorientation, inaccessible content, or severe responsive/performance failure | broken focus return, nonvirtualized large list, unreadable dark mode |
+| Moderate | Slows tasks or creates inconsistent Windows behavior with a workaround | hidden contextual command, weak empty state, inconsistent selection |
+| Minor | Polish issue with little task impact | spacing drift, inconsistent icon weight, unnecessary shadow |
+
+For each finding, cite the screen/control, trigger condition, user impact, and smallest robust correction. Avoid vague feedback such as “make it more modern.”
+
+## 8. Official sources
+
+- [WinUI 3 overview](https://learn.microsoft.com/windows/apps/winui/winui3/)
+- [Title bar customization](https://learn.microsoft.com/windows/apps/develop/title-bar?tabs=winui3)
+- [NavigationView title bar integration](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
+- [Responsive layouts with XAML](https://learn.microsoft.com/windows/apps/develop/ui/layouts-with-xaml)
+- [ListView and GridView](https://learn.microsoft.com/windows/apps/develop/ui/controls/listview-and-gridview)
+- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
+- [Accessibility checklist](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
diff --git a/references/input-accessibility.md b/references/input-accessibility.md
new file mode 100644
index 0000000..f48d1ee
--- /dev/null
+++ b/references/input-accessibility.md
@@ -0,0 +1,142 @@
+# Windows input and accessibility baseline
+
+## Contents
+
+1. Input parity
+2. Keyboard and focus
+3. Mouse, touch, pen, and drag
+4. UI Automation semantics
+5. Visual and cognitive accessibility
+6. Status, errors, and timing
+7. Accessibility test matrix
+8. Official sources
+
+## 1. Input parity
+
+Make every primary scenario possible with keyboard alone. Pointer hover, right-click, touch swipe, pen barrel button, drag-and-drop, and gestures may accelerate a task but must not be the only way to complete it.
+
+Use standard controls first because they already implement much of the focus, keyboard, pointer, touch, and UI Automation behavior. For every custom control, define:
+
+- automation role, name, value, state, and supported patterns;
+- tab-stop and inner arrow-key behavior;
+- keyboard activation and Escape behavior;
+- pointer cursor, hover, press, and context menu behavior;
+- touch target, manipulation threshold, and gesture alternative;
+- focus visuals, selected visuals, and high-contrast rendering.
+
+## 2. Keyboard and focus
+
+- Put actionable elements in the tab sequence; keep labels and decorative elements out.
+- Match tab order to visual and reading order. Prefer natural XAML order and use `TabIndex` only to correct a demonstrated issue.
+- Use arrow keys inside composite controls such as lists, menus, radio groups, tabs, and grids.
+- Set initial focus to the most useful safe element when a window, page, dialog, or task surface opens.
+- Return focus to the invoker when a flyout or dialog closes. After deletion, move focus to a predictable adjacent item or stable container.
+- Keep the platform focus visual visible. Do not encode focus only through a subtle color change.
+- Use access keys for visible commands and form navigation; use keyboard accelerators for frequent or standard actions.
+- Show accelerators in menus and tooltips where users learn commands.
+- Allow Escape to close dismissible UI or cancel the current transient mode. Do not discard unsaved work silently.
+- Ensure Enter and Space activate controls according to standard control behavior; do not invent conflicting key semantics.
+
+Use familiar shortcuts only when the command truly has the familiar meaning:
+
+| Shortcut | Expected meaning |
+|---|---|
+| `Ctrl+N` | new item/document/window as appropriate |
+| `Ctrl+O` | open |
+| `Ctrl+S` | save |
+| `Ctrl+Z` / `Ctrl+Y` or `Ctrl+Shift+Z` | undo / redo, consistent with the app domain |
+| `Ctrl+F` | search or find |
+| `F5` | refresh when refresh is meaningful |
+| `Delete` | delete selected item, with undo or confirmation based on consequence |
+| `Alt+Left` | back when the app has navigation history |
+| `F6` | move between major panes in complex workspaces |
+
+Do not override operating-system or assistive-technology shortcuts.
+
+## 3. Mouse, touch, pen, and drag
+
+### Mouse and pointer
+
+- Use hover to preview or accelerate, never to hide the only route to a command.
+- Provide a context menu for object-specific commands; expose frequent commands visibly as well.
+- Use tooltips for unfamiliar icons, truncated content, and shortcut education—not for essential instructions.
+- Keep selection and focus visually distinct in dense lists and grids.
+- Preserve target position during hover and press; avoid geometry changes that make the pointer chase a control.
+
+### Touch and pen
+
+Use platform controls at their default size where possible. For custom targets, meet the Windows touch baseline:
+
+- target at least 40 × 40 epx, even if the visible glyph is smaller;
+- a 32 epx-tall target can be acceptable when it is at least 120 epx wide;
+- for touch-optimized experiences, prefer 44 × 44 epx with at least 4 epx visible separation;
+- enlarge frequent or high-consequence targets beyond the minimum;
+- do not place destructive targets tightly beside routine actions.
+
+Support mouse precision without making touch impossible. Make scrolling, zoom, selection, and pen input coexist without gesture conflicts.
+
+### Drag and drop
+
+Show a clear drag affordance, valid targets, insertion position, forbidden states, and completion feedback. Use a movement threshold to prevent accidental drags. Always provide keyboard and menu commands such as Move up/down, Move to, Attach, or Import for critical drag operations.
+
+## 4. UI Automation semantics
+
+Accessible names must be concise, unique enough in context, and action-oriented for commands.
+
+- Let standard controls promote visible text when that produces the correct name.
+- Set `AutomationProperties.Name` explicitly for icon-only buttons, meaningful images, custom-drawn content, ambiguous repeated controls, or controls whose visible text does not describe the action.
+- Associate form labels with fields through `AutomationProperties.LabeledBy` where applicable.
+- Put supplemental instructions in help text or accessible descriptions; do not stuff them into the name.
+- Expose selection, checked, expanded, pressed, read-only, required, invalid, busy, and disabled states through the correct control or automation peer.
+- Mark decorative images and duplicate glyphs so they do not create noise.
+- Implement the appropriate UI Automation patterns for custom controls; an accessible name alone is insufficient.
+
+Do not add an explicit name to every control mechanically. Duplicate or stale names can make the screen-reader experience worse.
+
+## 5. Visual and cognitive accessibility
+
+- Maintain at least 4.5:1 text contrast in the normal light and dark themes.
+- Test high contrast; do not use a high-contrast theme as a substitute for adequate normal-theme contrast.
+- Pair color with text, shape, icon, position, or pattern for errors, selection, and status.
+- Preserve visible focus, current selection, and input validation at all theme states.
+- Support Windows text-size settings and display scaling without clipped text, inaccessible controls, or lost commands.
+- Prefer wrapping and adaptive height to truncation. Test long localized strings, narrow windows, and right-to-left layout when the product supports such locales.
+- Use plain, specific writing. Put the decision or recovery action first; avoid blame and error codes without explanation.
+- Avoid flashing and nonessential repetitive animation. Respect system animation preferences and keep interaction possible while motion runs.
+- Provide captions or transcripts for meaningful audio/video and text alternatives for informative graphics.
+
+## 6. Status, errors, and timing
+
+Announce important asynchronous state changes without stealing focus. Use a suitable live-region or standard control behavior for loading completion, errors, and background status.
+
+Error feedback must answer:
+
+1. What failed?
+2. What user work was preserved?
+3. What can the user do now?
+
+Place field errors near the field and summarize multiple errors at the task level when useful. Move focus only when it helps recovery, such as focusing the first invalid field after submit.
+
+Do not auto-dismiss critical errors. Give users enough time to read transient status, pause time limits when feasible, and provide a persistent history for important background operations or notifications.
+
+## 7. Accessibility test matrix
+
+- [ ] Complete primary flows with keyboard only.
+- [ ] Verify logical Tab, Shift+Tab, arrow, Enter, Space, Escape, access-key, and accelerator behavior.
+- [ ] Test Narrator reading order, names, roles, values, states, and live announcements.
+- [ ] Inspect the UI Automation tree with Accessibility Insights for Windows or Inspect.
+- [ ] Test light, dark, and at least one high-contrast theme.
+- [ ] Measure text contrast and verify that color is not the only cue.
+- [ ] Test Windows text-size changes, display scale changes, Magnifier, and narrow windows.
+- [ ] Test mouse, touch when supported, context menus, and alternatives to drag/hover.
+- [ ] Check long strings, localization expansion, and any supported right-to-left language.
+- [ ] Add automated accessibility checks for critical screens and flows where the test stack supports them.
+
+## 8. Official sources
+
+- [Accessibility checklist for Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
+- [Keyboard interactions](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
+- [Guidelines for touch targets](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
+- [Touch interactions](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions)
+- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
+- [Accessibility testing](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing)
diff --git a/references/windows-foundations.md b/references/windows-foundations.md
new file mode 100644
index 0000000..9a94b30
--- /dev/null
+++ b/references/windows-foundations.md
@@ -0,0 +1,129 @@
+# Windows visual and layout foundations
+
+## Contents
+
+1. Design principles
+2. Visual foundations
+3. Layout and responsive behavior
+4. Color and themes
+5. Materials and elevation
+6. Typography, icons, and motion
+7. Foundation review checklist
+8. Official sources
+
+## 1. Design principles
+
+Use the current Windows 11 principles as evaluation questions:
+
+| Principle | Ask |
+|---|---|
+| Effortless | Can users complete the primary task with focus, precision, and little interpretation? |
+| Calm | Is secondary chrome quiet enough for content and current work to dominate? |
+| Personal | Does the app respect theme, accent, text size, input, and user preferences? |
+| Familiar | Do navigation, commands, selection, windowing, and feedback behave like Windows? |
+| Complete + Coherent | Do screens, windows, states, and input modes feel like one system? |
+
+Do not substitute the older Fluent vocabulary of light, depth, motion, material, and scale for these five product principles. Treat color, elevation, iconography, materials, geometry, typography, and motion as visual foundations.
+
+## 2. Visual foundations
+
+Build a semantic token layer instead of styling each screen independently:
+
+- `surface.base`, `surface.layer`, `surface.overlay`;
+- `text.primary`, `text.secondary`, `text.disabled`;
+- `accent.default`, `accent.hover`, `accent.pressed`, `accent.disabled`;
+- `status.success`, `status.caution`, `status.critical`, `status.informational`;
+- `stroke.control`, `stroke.divider`, `focus.stroke`;
+- `space.1` through `space.n`, `radius.control`, `radius.overlay`;
+- `motion.fast`, `motion.normal`, and shared easing tokens.
+
+Map these semantics to WinUI theme resources where available. Keep brand tokens above platform tokens so light, dark, and high-contrast mappings remain explicit.
+
+Use one primary accent action per local task area. Use size, spacing, alignment, and weight before adding more colors or surfaces.
+
+## 3. Layout and responsive behavior
+
+Design in effective pixels (epx). Use multiples of 4 epx for sizes, margins, and positions when practical; text size is not restricted to this grid.
+
+Use the current Windows width classes as starting points, then adjust only when content demonstrates a real need:
+
+| Class | Effective width | Typical response |
+|---|---:|---|
+| Small | `<= 640` | single pane, collapsed or minimal navigation, stacked form, deferred secondary content |
+| Medium | `641–1007` | compact navigation, list/detail may switch between one and two panes |
+| Large | `>= 1008` | persistent navigation or multi-pane workspace when it improves the task |
+
+Use the actual content region or window width, not monitor resolution. Validate at the app's supported minimum size, Windows Snap widths, restored windows, maximized windows, and across display scaling changes.
+
+Apply responsive techniques deliberately:
+
+- **Reflow:** wrap or stack content without changing meaning.
+- **Resize:** let flexible regions absorb space; constrain readable text measure.
+- **Reposition:** move secondary panels or commands while preserving order.
+- **Reveal:** progressively expose low-priority content as room grows.
+- **Replace:** switch to a more suitable navigation or presentation control.
+- **Re-architect:** use a different workflow only when a compact window cannot support the same structure.
+
+Define the narrow state as the safe default, then use `VisualStateManager` and `AdaptiveTrigger` for wider states. Prefer control-provided thresholds such as `NavigationView` compact/open pane widths when those express the intended behavior. Avoid fixed widths for content that must localize or scale.
+
+## 4. Color and themes
+
+- Use `{ThemeResource ...}` for colors and brushes that must update when the theme changes.
+- Test light, dark, and high contrast independently; do not generate dark mode by inversion.
+- Respect the system accent color unless product identity or domain semantics justify a controlled brand accent.
+- Maintain at least 4.5:1 contrast for normal text. Use icons, text, or patterns in addition to semantic color.
+- Do not encode state only through reduced opacity. Preserve recognizable text, focus, selection, and disabled semantics.
+- Never place critical text over a material or image without a deterministic readable fallback.
+
+Prefer system resources such as text fill, control fill, stroke, accent fill, and system status brushes. Verify resource names against the project's Windows App SDK version before emitting code.
+
+## 5. Materials and elevation
+
+Use material to clarify layers, not to decorate every container:
+
+| Need | Preferred mechanism | Notes |
+|---|---|---|
+| Main window background | `MicaBackdrop` | Windows 11; solid fallback on Windows 10 |
+| Desktop-see-through window | `DesktopAcrylicBackdrop` | More visually active; use only when the experience benefits |
+| Material on a specific region | `SystemBackdropElement` | Requires Windows App SDK 1.6.3 or later |
+| Blur content inside the window | in-app `AcrylicBrush` | Does not show the desktop behind the app |
+| Simple content surface | theme solid color | Often the clearest and cheapest choice |
+
+Do not use UWP `HostBackdrop` patterns in WinUI 3. Allow system fallback when transparency is disabled, hardware is insufficient, Battery Saver suppresses Acrylic, Remote Desktop is active, or high contrast is enabled. Ensure the fallback color preserves hierarchy and contrast.
+
+Use elevation only to communicate overlap, focus, or transient UI. Prefer system shadows and overlay behavior. Do not introduce an external shadow control merely to make cards look raised.
+
+## 6. Typography, icons, and motion
+
+Use Segoe UI Variable and the WinUI type ramp by default. Reuse platform text styles rather than copying numeric sizes throughout XAML. Use regular body weight, stronger titles or labels, tabular figures for aligned numeric data, and wrapping before truncation. When truncation is unavoidable, expose the full value through an accessible tooltip or detail surface.
+
+Use `SymbolIcon`, `FontIcon` with Segoe Fluent Icons, or a consistent vector asset set. Keep icon metaphor, size, stroke/fill style, and alignment consistent. Give unfamiliar or icon-only commands an accessible name and tooltip. Do not use emoji as navigation or command icons.
+
+Use motion to explain causality, hierarchy, and continuity:
+
+- give immediate pointer/press feedback;
+- prefer platform transitions and connected animations where they clarify movement;
+- animate compositor-friendly properties such as opacity and transforms;
+- keep motion interruptible and never use it to delay input;
+- reduce or remove nonessential motion when system animation settings request it;
+- avoid perpetual decorative movement in productivity surfaces.
+
+## 7. Foundation review checklist
+
+- [ ] The UI reflects Effortless, Calm, Personal, Familiar, and Complete + Coherent.
+- [ ] Semantic tokens cover themes and all interaction states.
+- [ ] Layout is proven at compact, medium, wide, snapped, and scaled conditions.
+- [ ] Spacing and geometry follow a coherent 4 epx rhythm.
+- [ ] Material choice communicates a layer and has a solid fallback.
+- [ ] Typography remains readable under text scaling and localization.
+- [ ] Icons use one language and are not emoji.
+- [ ] Motion communicates change and respects user settings.
+
+## 8. Official sources
+
+- [Windows design principles](https://learn.microsoft.com/windows/apps/design/design-principles)
+- [Windows design guidelines](https://learn.microsoft.com/windows/apps/design/guidelines-overview)
+- [Screen sizes and breakpoints](https://learn.microsoft.com/windows/apps/design/layout/screen-sizes-and-breakpoints-for-responsive-design)
+- [Content layout and spacing](https://learn.microsoft.com/windows/apps/design/basics/content-basics)
+- [Materials in Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/materials)
+- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)