From 35c58c59a6745ee31b611116890f93b571867e19 Mon Sep 17 00:00:00 2001 From: OpenCode Bot Date: Mon, 20 Jul 2026 14:50:33 +0200 Subject: [PATCH 1/4] chore(skills): update ui-ux-pro-max to upstream v2.11.0 (84 styles, 192 palettes, 22 stacks) Vendors the latest ui-ux-pro-max-skill bundle from github.com/nextlevelbuilder/ui-ux-pro-max-skill (MIT license) into all three bundle locations: skills/ui-ux-pro-max/, packages/codegraph/data/ skill/ui-ux-pro-max/, and .agents/skills/ui-ux-pro-max/. data/, scripts/, and references/ are wholesale-replaced to match upstream exactly (adds google-fonts.csv, motion.csv, references/, validate_data.py, tests/, and 6 new stack files; renames web-interface.csv -> app-interface.csv); local evals/ and learnings.md are left untouched. Also syncs the lifecycle-skills SKILL.md-only mirror and adds a version: 2.11.0 frontmatter line to every copied SKILL.md. MIT attribution: LICENSE + NOTICE (crediting nextlevelbuilder/ ui-ux-pro-max-skill) added to each of the 3 bundle locations. Security review (scripts/*.py) before vendoring: no network calls, no exec/eval/subprocess/os.system, no secret/credential/env access beyond a benign COLORTERM check, and all file writes are confined to /design-system// with path-traversal protection via safe_slug(). Verdict: safe to vendor. Local dev DB (.codegraph/graph.db, gitignored) updated surgically via direct UPDATE of the ui-ux-pro-max row's content/description/updated_at -- no full re-import. Prod skill routing (memory.fl1.it) is untouched and needs the separate deploy pipeline in packages/codegraph/docs/DEPLOY-SKILLS.md. Co-Authored-By: Claude Opus 4.8 --- .agents/skills/ui-ux-pro-max/LICENSE | 21 + .agents/skills/ui-ux-pro-max/NOTICE | 1 + .agents/skills/ui-ux-pro-max/SKILL.md | 410 +--- .../ui-ux-pro-max/data/app-interface.csv | 31 + .agents/skills/ui-ux-pro-max/data/charts.csv | 52 +- .agents/skills/ui-ux-pro-max/data/colors.csv | 290 ++- .../ui-ux-pro-max/data/google-fonts.csv | 1924 +++++++++++++++++ .agents/skills/ui-ux-pro-max/data/icons.csv | 205 +- .agents/skills/ui-ux-pro-max/data/landing.csv | 66 +- .agents/skills/ui-ux-pro-max/data/motion.csv | 17 + .../skills/ui-ux-pro-max/data/products.csv | 290 ++- .../ui-ux-pro-max/data/stacks/angular.csv | 51 + .../ui-ux-pro-max/data/stacks/astro.csv | 22 +- .../ui-ux-pro-max/data/stacks/avalonia.csv | 57 + .../ui-ux-pro-max/data/stacks/flutter.csv | 106 +- .../data/stacks/html-tailwind.csv | 112 +- .../ui-ux-pro-max/data/stacks/javafx.csv | 76 + .../ui-ux-pro-max/data/stacks/laravel.csv | 51 + .../ui-ux-pro-max/data/stacks/nextjs.csv | 106 +- .../ui-ux-pro-max/data/stacks/nuxt-ui.csv | 26 +- .../data/stacks/react-native.csv | 104 +- .../ui-ux-pro-max/data/stacks/react.csv | 108 +- .../ui-ux-pro-max/data/stacks/svelte.csv | 108 +- .../ui-ux-pro-max/data/stacks/swiftui.csv | 102 +- .../ui-ux-pro-max/data/stacks/threejs.csv | 54 + .../skills/ui-ux-pro-max/data/stacks/uno.csv | 60 + .../skills/ui-ux-pro-max/data/stacks/uwp.csv | 56 + .../skills/ui-ux-pro-max/data/stacks/vue.csv | 100 +- .../ui-ux-pro-max/data/stacks/winui.csv | 60 + .../skills/ui-ux-pro-max/data/stacks/wpf.csv | 57 + .agents/skills/ui-ux-pro-max/data/styles.csv | 153 +- .../skills/ui-ux-pro-max/data/typography.csv | 131 +- .../ui-ux-pro-max/data/ui-reasoning.csv | 253 ++- .../ui-ux-pro-max/data/ux-guidelines.csv | 198 +- .../ui-ux-pro-max/data/web-interface.csv | 31 - .../ui-ux-pro-max/references/pro-rules.md | 109 + .../references/quick-reference.md | 240 ++ .agents/skills/ui-ux-pro-max/scripts/core.py | 331 ++- .../ui-ux-pro-max/scripts/design_system.py | 538 ++++- .../skills/ui-ux-pro-max/scripts/search.py | 276 ++- .../ui-ux-pro-max/scripts/tests/test_core.py | 134 ++ .../ui-ux-pro-max/scripts/validate_data.py | 114 + .../lifecycle-skills/ui-ux-pro-max/SKILL.md | 410 +--- .../data/skill/ui-ux-pro-max/LICENSE | 21 + .../codegraph/data/skill/ui-ux-pro-max/NOTICE | 1 + .../data/skill/ui-ux-pro-max/SKILL.md | 410 +--- .../ui-ux-pro-max/data/app-interface.csv | 31 + .../data/skill/ui-ux-pro-max/data/charts.csv | 52 +- .../data/skill/ui-ux-pro-max/data/colors.csv | 290 ++- .../skill/ui-ux-pro-max/data/google-fonts.csv | 1924 +++++++++++++++++ .../data/skill/ui-ux-pro-max/data/icons.csv | 205 +- .../data/skill/ui-ux-pro-max/data/landing.csv | 66 +- .../data/skill/ui-ux-pro-max/data/motion.csv | 17 + .../skill/ui-ux-pro-max/data/products.csv | 290 ++- .../ui-ux-pro-max/data/stacks/angular.csv | 51 + .../skill/ui-ux-pro-max/data/stacks/astro.csv | 22 +- .../ui-ux-pro-max/data/stacks/avalonia.csv | 57 + .../ui-ux-pro-max/data/stacks/flutter.csv | 106 +- .../data/stacks/html-tailwind.csv | 112 +- .../ui-ux-pro-max/data/stacks/javafx.csv | 76 + .../ui-ux-pro-max/data/stacks/laravel.csv | 51 + .../ui-ux-pro-max/data/stacks/nextjs.csv | 106 +- .../ui-ux-pro-max/data/stacks/nuxt-ui.csv | 26 +- .../data/stacks/react-native.csv | 104 +- .../skill/ui-ux-pro-max/data/stacks/react.csv | 108 +- .../ui-ux-pro-max/data/stacks/svelte.csv | 108 +- .../ui-ux-pro-max/data/stacks/swiftui.csv | 102 +- .../ui-ux-pro-max/data/stacks/threejs.csv | 54 + .../skill/ui-ux-pro-max/data/stacks/uno.csv | 60 + .../skill/ui-ux-pro-max/data/stacks/uwp.csv | 56 + .../skill/ui-ux-pro-max/data/stacks/vue.csv | 100 +- .../skill/ui-ux-pro-max/data/stacks/winui.csv | 60 + .../skill/ui-ux-pro-max/data/stacks/wpf.csv | 57 + .../data/skill/ui-ux-pro-max/data/styles.csv | 153 +- .../skill/ui-ux-pro-max/data/typography.csv | 131 +- .../skill/ui-ux-pro-max/data/ui-reasoning.csv | 253 ++- .../ui-ux-pro-max/data/ux-guidelines.csv | 198 +- .../ui-ux-pro-max/data/web-interface.csv | 31 - .../ui-ux-pro-max/references/pro-rules.md | 109 + .../references/quick-reference.md | 240 ++ .../data/skill/ui-ux-pro-max/scripts/core.py | 331 ++- .../ui-ux-pro-max/scripts/design_system.py | 538 ++++- .../skill/ui-ux-pro-max/scripts/search.py | 276 ++- .../ui-ux-pro-max/scripts/tests/test_core.py | 134 ++ .../ui-ux-pro-max/scripts/validate_data.py | 114 + skills/ui-ux-pro-max/LICENSE | 21 + skills/ui-ux-pro-max/NOTICE | 1 + skills/ui-ux-pro-max/SKILL.md | 410 +--- skills/ui-ux-pro-max/data/app-interface.csv | 31 + skills/ui-ux-pro-max/data/charts.csv | 52 +- skills/ui-ux-pro-max/data/colors.csv | 290 ++- skills/ui-ux-pro-max/data/google-fonts.csv | 1924 +++++++++++++++++ skills/ui-ux-pro-max/data/icons.csv | 205 +- skills/ui-ux-pro-max/data/landing.csv | 66 +- skills/ui-ux-pro-max/data/motion.csv | 17 + skills/ui-ux-pro-max/data/products.csv | 290 ++- skills/ui-ux-pro-max/data/stacks/angular.csv | 51 + skills/ui-ux-pro-max/data/stacks/astro.csv | 22 +- skills/ui-ux-pro-max/data/stacks/avalonia.csv | 57 + skills/ui-ux-pro-max/data/stacks/flutter.csv | 106 +- .../data/stacks/html-tailwind.csv | 112 +- skills/ui-ux-pro-max/data/stacks/javafx.csv | 76 + skills/ui-ux-pro-max/data/stacks/laravel.csv | 51 + skills/ui-ux-pro-max/data/stacks/nextjs.csv | 106 +- skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv | 26 +- .../data/stacks/react-native.csv | 104 +- skills/ui-ux-pro-max/data/stacks/react.csv | 108 +- skills/ui-ux-pro-max/data/stacks/svelte.csv | 108 +- skills/ui-ux-pro-max/data/stacks/swiftui.csv | 102 +- skills/ui-ux-pro-max/data/stacks/threejs.csv | 54 + skills/ui-ux-pro-max/data/stacks/uno.csv | 60 + skills/ui-ux-pro-max/data/stacks/uwp.csv | 56 + skills/ui-ux-pro-max/data/stacks/vue.csv | 100 +- skills/ui-ux-pro-max/data/stacks/winui.csv | 60 + skills/ui-ux-pro-max/data/stacks/wpf.csv | 57 + skills/ui-ux-pro-max/data/styles.csv | 153 +- skills/ui-ux-pro-max/data/typography.csv | 131 +- skills/ui-ux-pro-max/data/ui-reasoning.csv | 253 ++- skills/ui-ux-pro-max/data/ux-guidelines.csv | 198 +- skills/ui-ux-pro-max/data/web-interface.csv | 31 - skills/ui-ux-pro-max/references/pro-rules.md | 109 + .../references/quick-reference.md | 240 ++ skills/ui-ux-pro-max/scripts/core.py | 331 ++- skills/ui-ux-pro-max/scripts/design_system.py | 538 ++++- skills/ui-ux-pro-max/scripts/search.py | 276 ++- .../ui-ux-pro-max/scripts/tests/test_core.py | 134 ++ skills/ui-ux-pro-max/scripts/validate_data.py | 114 + 127 files changed, 16601 insertions(+), 5502 deletions(-) create mode 100644 .agents/skills/ui-ux-pro-max/LICENSE create mode 100644 .agents/skills/ui-ux-pro-max/NOTICE create mode 100644 .agents/skills/ui-ux-pro-max/data/app-interface.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/google-fonts.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/motion.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/angular.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/avalonia.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/javafx.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/laravel.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/threejs.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/uno.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/uwp.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/winui.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/wpf.csv delete mode 100644 .agents/skills/ui-ux-pro-max/data/web-interface.csv create mode 100644 .agents/skills/ui-ux-pro-max/references/pro-rules.md create mode 100644 .agents/skills/ui-ux-pro-max/references/quick-reference.md create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_core.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/validate_data.py create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/LICENSE create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/NOTICE create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/app-interface.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/google-fonts.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/motion.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/angular.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/avalonia.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/javafx.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/laravel.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/threejs.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/uno.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/uwp.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/winui.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/stacks/wpf.csv delete mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/data/web-interface.csv create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/references/pro-rules.md create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/references/quick-reference.md create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/scripts/tests/test_core.py create mode 100644 packages/codegraph/data/skill/ui-ux-pro-max/scripts/validate_data.py create mode 100644 skills/ui-ux-pro-max/LICENSE create mode 100644 skills/ui-ux-pro-max/NOTICE create mode 100644 skills/ui-ux-pro-max/data/app-interface.csv create mode 100644 skills/ui-ux-pro-max/data/google-fonts.csv create mode 100644 skills/ui-ux-pro-max/data/motion.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/angular.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/avalonia.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/javafx.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/laravel.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/threejs.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/uno.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/uwp.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/winui.csv create mode 100644 skills/ui-ux-pro-max/data/stacks/wpf.csv delete mode 100644 skills/ui-ux-pro-max/data/web-interface.csv create mode 100644 skills/ui-ux-pro-max/references/pro-rules.md create mode 100644 skills/ui-ux-pro-max/references/quick-reference.md create mode 100644 skills/ui-ux-pro-max/scripts/tests/test_core.py create mode 100644 skills/ui-ux-pro-max/scripts/validate_data.py diff --git a/.agents/skills/ui-ux-pro-max/LICENSE b/.agents/skills/ui-ux-pro-max/LICENSE new file mode 100644 index 0000000..1e71cbf --- /dev/null +++ b/.agents/skills/ui-ux-pro-max/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Next Level Builder + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.agents/skills/ui-ux-pro-max/NOTICE b/.agents/skills/ui-ux-pro-max/NOTICE new file mode 100644 index 0000000..f9489ca --- /dev/null +++ b/.agents/skills/ui-ux-pro-max/NOTICE @@ -0,0 +1 @@ +This bundle vendors content from nextlevelbuilder/ui-ux-pro-max-skill (https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), licensed under the MIT License. See LICENSE in this directory for the full license text. diff --git a/.agents/skills/ui-ux-pro-max/SKILL.md b/.agents/skills/ui-ux-pro-max/SKILL.md index 6b29081..3871a63 100644 --- a/.agents/skills/ui-ux-pro-max/SKILL.md +++ b/.agents/skills/ui-ux-pro-max/SKILL.md @@ -1,393 +1,197 @@ --- name: ui-ux-pro-max -description: > - UI/UX design intelligence with 50 styles, 21 palettes, 50 font pairings, 20 charts, - 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). - Use when designing or reviewing UI: websites, dashboards, landing pages, admin panels, - e-commerce, SaaS, mobile apps. Use when user asks to plan, build, design, implement, - review, fix, improve, or check UI/UX code, color palette, typography, or accessibility. - Covers glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode. -version: 1.0.0 +description: "UI/UX design intelligence for web and mobile. Searchable local database with 84 styles, 192 color palettes, 74 font pairings, 192 product types, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 stacks (React, Next.js, Vue, Nuxt, Svelte, Astro, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, Jetpack Compose, Angular, Laravel, JavaFX, WPF, WinUI, Avalonia, Uno Platform, UWP, Three.js, and HTML/CSS). Use when designing, building, or reviewing UI: pages, components, color schemes, typography, layout, accessibility, animation, or data visualization." +version: 2.11.0 --- # UI/UX Pro Max - Design Intelligence -Comprehensive design guide for web and mobile applications. Contains 50+ styles, 97 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 9 technology stacks. Searchable database with priority-based recommendations. +Searchable database of UI/UX design rules with priority-based recommendations: 84 styles, 192 color palettes, 74 font pairings, 192 product types with reasoning rules, 98 UX guidelines, 104 icon entries, 16 GSAP motion presets, and 25 chart types across 22 technology stacks. ## When to Apply -Reference these guidelines when: -- Designing new UI components or pages -- Choosing color palettes and typography -- Reviewing code for UX issues -- Building landing pages or dashboards -- Implementing accessibility requirements +Use this Skill when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**: designing new pages, creating/refactoring UI components, choosing color/typography/spacing/layout systems, reviewing UI for UX/accessibility/consistency, implementing navigation/animation/responsive behavior, or improving perceived quality and usability. -## Rule Categories by Priority - -| Priority | Category | Impact | Domain | -|----------|----------|--------|--------| -| 1 | Accessibility | CRITICAL | `ux` | -| 2 | Touch & Interaction | CRITICAL | `ux` | -| 3 | Performance | HIGH | `ux` | -| 4 | Layout & Responsive | HIGH | `ux` | -| 5 | Typography & Color | MEDIUM | `typography`, `color` | -| 6 | Animation | MEDIUM | `ux` | -| 7 | Style Selection | MEDIUM | `style`, `product` | -| 8 | Charts & Data | LOW | `chart` | - -## Quick Reference - -### 1. Accessibility (CRITICAL) - -- `color-contrast` - Minimum 4.5:1 ratio for normal text -- `focus-states` - Visible focus rings on interactive elements -- `alt-text` - Descriptive alt text for meaningful images -- `aria-labels` - aria-label for icon-only buttons -- `keyboard-nav` - Tab order matches visual order -- `form-labels` - Use label with for attribute - -### 2. Touch & Interaction (CRITICAL) - -- `touch-target-size` - Minimum 44x44px touch targets -- `hover-vs-tap` - Use click/tap for primary interactions -- `loading-buttons` - Disable button during async operations -- `error-feedback` - Clear error messages near problem -- `cursor-pointer` - Add cursor-pointer to clickable elements - -### 3. Performance (HIGH) - -- `image-optimization` - Use WebP, srcset, lazy loading -- `reduced-motion` - Check prefers-reduced-motion -- `content-jumping` - Reserve space for async content - -### 4. Layout & Responsive (HIGH) +Skip it for pure backend logic, API/database design, non-visual performance work, infrastructure/DevOps, or non-visual scripts — unless the task changes how something **looks, feels, moves, or is interacted with**. -- `viewport-meta` - width=device-width initial-scale=1 -- `readable-font-size` - Minimum 16px body text on mobile -- `horizontal-scroll` - Ensure content fits viewport width -- `z-index-management` - Define z-index scale (10, 20, 30, 50) - -### 5. Typography & Color (MEDIUM) - -- `line-height` - Use 1.5-1.75 for body text -- `line-length` - Limit to 65-75 characters per line -- `font-pairing` - Match heading/body font personalities - -### 6. Animation (MEDIUM) - -- `duration-timing` - Use 150-300ms for micro-interactions -- `transform-performance` - Use transform/opacity, not width/height -- `loading-states` - Skeleton screens or spinners - -### 7. Style Selection (MEDIUM) - -- `style-match` - Match style to product type -- `consistency` - Use same style across all pages -- `no-emoji-icons` - Use SVG icons, not emojis - -### 8. Charts & Data (LOW) +## Rule Categories by Priority -- `chart-type` - Match chart type to data type -- `color-guidance` - Use accessible color palettes -- `data-table` - Provide table alternative for accessibility +*Follow priority 1→10 to decide which category to focus on first; use `--domain ` to query full details. The full rule text for every category lives in `references/quick-reference.md` — read it on demand rather than loading it every time.* -## How to Use +| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) | +|----------|----------|--------|--------|------------------------|------------------------| +| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels | +| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) | +| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS < 0.1) | Layout thrashing, Cumulative Layout Shift | +| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons | +| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom | +| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text < 12px body, Gray-on-gray, Raw hex in components | +| 7 | Animation | MEDIUM | `ux`, `gsap` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion | +| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront | +| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links | +| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning | -Search specific domains using the CLI tool below. +For the full rule list per category (all ~98 UX guidelines with rationale), read `references/quick-reference.md`. For app-specific polish rules (icons, touch feedback, dark mode contrast, safe areas) and the canonical pre-delivery checklist, read `references/pro-rules.md`. --- -## Prerequisites +## Running the search tool -Check if Python is installed: +The search script lives inside this skill's own directory, not the project directory. Always invoke it by its full path — do not assume a particular working directory: ```bash -python3 --version || python --version +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "" --domain ``` -If Python is not installed, install it based on user's OS: +If `python` is not found, try `python3`, then `py -3`. Requires Python 3.x, no external dependencies (see README for install instructions if Python is missing). -**macOS:** -```bash -brew install python3 -``` - -**Ubuntu/Debian:** -```bash -sudo apt update && sudo apt install python3 -``` - -**Windows:** -```powershell -winget install Python.Python.3.12 -``` - ---- - -## How to Use This Skill - -When user requests UI/UX work (design, build, create, implement, review, fix, improve), follow this workflow: +## Workflow ### Step 1: Analyze User Requirements -Extract key information from user request: -- **Product type**: SaaS, e-commerce, portfolio, dashboard, landing page, etc. -- **Style keywords**: minimal, playful, professional, elegant, dark mode, etc. -- **Industry**: healthcare, fintech, gaming, education, etc. -- **Stack**: React, Vue, Next.js, or default to `html-tailwind` +Extract from the user request: +- **Product type**: SaaS, e-commerce, portfolio, dashboard, entertainment, tool, productivity, or hybrid +- **Target audience & context**: age group, usage context (commute, leisure, work) +- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc. +- **Stack**: detect from the project — check `package.json` deps (react/next/vue/svelte/nuxt/@angular), `pubspec.yaml` (Flutter), `*.xcodeproj`/`Package.swift` (SwiftUI), `composer.json` (Laravel), or React Native markers (`app.json` + `react-native` dep). If nothing is detectable, ask the user or default to `html-tailwind`. **Never assume a stack** — a hardcoded default silently misroutes every recommendation. -### Step 2: Generate Design System (REQUIRED) +### Step 2: Generate Design System (REQUIRED for new pages/projects) -**Always start with `--design-system`** to get comprehensive recommendations with reasoning: +Always start with `--design-system` to get comprehensive recommendations with reasoning: ```bash -python3 skills/ui-ux-pro-max/scripts/search.py " " --design-system [-p "Project Name"] +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" " " --design-system [-p "Project Name"] ``` -This command: -1. Searches 5 domains in parallel (product, style, color, landing, typography) -2. Applies reasoning rules from `ui-reasoning.csv` to select best matches -3. Returns complete design system: pattern, style, colors, typography, effects -4. Includes anti-patterns to avoid +This searches product/style/color/landing/typography domains in parallel, applies reasoning rules from `ui-reasoning.csv`, and returns pattern, style, colors, typography, effects, and anti-patterns to avoid. **Example:** ```bash -python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa" +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "beauty spa wellness service" --design-system -p "Serenity Spa" ``` ### Step 2b: Persist Design System (Master + Overrides Pattern) -To save the design system for **hierarchical retrieval across sessions**, add `--persist`: +To save the design system for retrieval across sessions, add `--persist` **and always pass `--output-dir` pointed at the project root** — without it, files are written relative to whatever directory the tool happens to run from: ```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --design-system --persist -p "Project Name" +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "" --design-system --persist -p "Project Name" --output-dir "" ``` This creates: -- `design-system/MASTER.md` — Global Source of Truth with all design rules -- `design-system/pages/` — Folder for page-specific overrides +- `design-system//MASTER.md` — Global Source of Truth +- `design-system//pages/` — Folder for page-specific overrides + +With a page-specific override, add `--page "dashboard"` to also create `design-system//pages/dashboard.md`. + +If `design-system//MASTER.md` already exists, `--persist` **skips writing and leaves it untouched** unless you also pass `--force` — check whether it exists first (and read it) before regenerating, so you don't silently discard prior decisions the user or a teammate made. + +**Retrieval when building a specific page:** +1. Read `design-system//MASTER.md` +2. Check if `design-system//pages/.md` exists — if so, its rules override Master +3. Otherwise use Master rules exclusively + +### Step 2c: Design Dials (optional) + +Three optional 1-10 sliders that tune `--design-system` output without changing your query. Add any combination of them to the same command: -**With page-specific override:** ```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --design-system --persist -p "Project Name" --page "dashboard" +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "" --design-system --variance <1-10> --motion <1-10> --density <1-10> ``` -This also creates: -- `design-system/pages/dashboard.md` — Page-specific deviations from Master +| Dial | Low (1-3) | Mid (4-7) | High (8-10) | +|------|-----------|-----------|-------------| +| `--variance` | Centered / minimal (biases toward Minimalism-style categories) | Balanced / modern | Bold / asymmetric (biases toward Brutalism, Bento Grids) | +| `--motion` | Subtle micro-interactions | Standard scroll/stagger motion | Complex choreography (pin, Flip, SplitText) | +| `--density` | Spacious (24-96px spacing scale) | Standard (16-64px, current default) | Dense/dashboard (8-32px spacing scale) | -**How hierarchical retrieval works:** -1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md` -2. If the page file exists, its rules **override** the Master file -3. If not, use `design-system/MASTER.md` exclusively +- `--motion` attaches a ready-to-use GSAP snippet (with framework notes, Do/Don't, and performance notes) pulled from `--domain gsap`, matched to the resolved tier (Subtle/Standard/Complex). +- `--density` overrides the `--space-*` CSS variable table in the ASCII/markdown/MASTER.md output — use it for dashboards (high) vs. marketing pages (low) without hand-editing tokens. +- Leaving a dial unset keeps that part of the output exactly as it was before (no behavior change). -**Context-aware retrieval prompt:** -``` -I am building the [Page Name] page. Please read design-system/MASTER.md. -Also check if design-system/pages/[page-name].md exists. -If the page file exists, prioritize its rules. -If not, use the Master rules exclusively. -Now, generate the code... +**Example:** +```bash +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "internal analytics dashboard" --design-system --variance 8 --motion 7 --density 8 -p "Ops Console" ``` ### Step 3: Supplement with Detailed Searches (as needed) -After getting the design system, use domain searches to get additional details: - ```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --domain [-n ] +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "" --domain [-n ] ``` -**When to use detailed searches:** - | Need | Domain | Example | |------|--------|---------| +| Product type patterns | `product` | `--domain product "entertainment social"` | | More style options | `style` | `--domain style "glassmorphism dark"` | +| Color palettes | `color` | `--domain color "entertainment vibrant"` | +| Font pairings | `typography` | `--domain typography "playful modern"` | +| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` | | Chart recommendations | `chart` | `--domain chart "real-time dashboard"` | | UX best practices | `ux` | `--domain ux "animation accessibility"` | -| Alternative fonts | `typography` | `--domain typography "elegant luxury"` | -| Landing structure | `landing` | `--domain landing "hero social-proof"` | +| Landing page structure | `landing` | `--domain landing "hero social-proof"` | +| Icon recommendations | `icons` | `--domain icons "navigation outline"` | +| GSAP animation presets | `gsap` | `--domain gsap "scroll reveal stagger"` | +| React/Next.js performance | `react` | `--domain react "rerender memo list"` | +| App/native interface guidelines | `web` | `--domain web "accessibilityLabel touch safe-areas"` | -### Step 4: Stack Guidelines (Default: html-tailwind) +Domain is auto-detected from the query if `--domain` is omitted — but auto-detection can misroute overlapping terms (e.g. "font" matches both `typography` and `google-fonts`). If results look off-topic, pass `--domain` explicitly. -Get implementation-specific best practices. If user doesn't specify a stack, **default to `html-tailwind`**. +### Step 4: Stack Guidelines ```bash -python3 skills/ui-ux-pro-max/scripts/search.py "" --stack html-tailwind +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "" --stack ``` -Available stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose` +**Available stacks:** `react`, `nextjs`, `vue`, `svelte`, `astro`, `nuxtjs`, `nuxt-ui`, `angular`, `laravel`, `swiftui`, `react-native`, `flutter`, `jetpack-compose`, `html-tailwind`, `shadcn`, `threejs`, `javafx`, `wpf`, `winui`, `avalonia`, `uno`, `uwp`. Use the stack detected in Step 1. --- -## Search Reference - -### Available Domains - -| Domain | Use For | Example Keywords | -|--------|---------|------------------| -| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service | -| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism | -| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern | -| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service | -| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof | -| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie | -| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading | -| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache | -| `web` | Web interface guidelines | aria, focus, keyboard, semantic, virtualize | -| `prompt` | AI prompts, CSS keywords | (style name) | - -### Available Stacks - -| Stack | Focus | -|-------|-------| -| `html-tailwind` | Tailwind utilities, responsive, a11y (DEFAULT) | -| `react` | State, hooks, performance, patterns | -| `nextjs` | SSR, routing, images, API routes | -| `vue` | Composition API, Pinia, Vue Router | -| `svelte` | Runes, stores, SvelteKit | -| `swiftui` | Views, State, Navigation, Animation | -| `react-native` | Components, Navigation, Lists | -| `flutter` | Widgets, State, Layout, Theming | -| `shadcn` | shadcn/ui components, theming, forms, patterns | -| `jetpack-compose` | Composables, Modifiers, State Hoisting, Recomposition | +## If a search returns 0 results ---- +Do not fabricate output. Instead: +1. Retry once with broader or differently-worded keywords (try product + style separately rather than combined). +2. If still empty, fall back to the priority table above and say explicitly to the user that this recommendation came from the built-in defaults, not a database match (e.g. "no palette match for X, using general SaaS defaults"). +3. Never present a 0-result search as if it returned data. ## Example Workflow -**User request:** "Làm landing page cho dịch vụ chăm sóc da chuyên nghiệp" - -### Step 1: Analyze Requirements -- Product type: Beauty/Spa service -- Style keywords: elegant, professional, soft -- Industry: Beauty/Wellness -- Stack: html-tailwind (default) - -### Step 2: Generate Design System (REQUIRED) - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service elegant" --design-system -p "Serenity Spa" -``` - -**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns. - -### Step 3: Supplement with Detailed Searches (as needed) +**User request:** "Make an AI search homepage." (stack detected as Next.js from `package.json`) ```bash -# Get UX guidelines for animation and accessibility -python3 skills/ui-ux-pro-max/scripts/search.py "animation accessibility" --domain ux +# Step 2: design system +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "AI search tool modern minimal" --design-system -p "AI Search" -# Get alternative typography options if needed -python3 skills/ui-ux-pro-max/scripts/search.py "elegant luxury serif" --domain typography -``` +# Step 3: supplement +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "search loading animation" --domain ux -### Step 4: Stack Guidelines - -```bash -python3 skills/ui-ux-pro-max/scripts/search.py "layout responsive form" --stack html-tailwind +# Step 4: stack guidelines +python "${CLAUDE_PLUGIN_ROOT}/.claude/skills/ui-ux-pro-max/scripts/search.py" "suspense streaming bundle" --stack nextjs ``` -**Then:** Synthesize design system + detailed searches and implement the design. - ---- +Then synthesize the design system + detailed searches and implement. ## Output Formats -The `--design-system` flag supports two output formats: - -```bash -# ASCII box (default) - best for terminal display -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system - -# Markdown - best for documentation -python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown -``` - ---- +`--design-system` supports `-f ascii` (default, terminal display), `-f markdown` (documentation), and `--json` (machine-readable, includes the raw design system dict plus persistence status). ## Tips for Better Results -1. **Be specific with keywords** - "healthcare SaaS dashboard" > "app" -2. **Search multiple times** - Different keywords reveal different insights -3. **Combine domains** - Style + Typography + Color = Complete design system -4. **Always check UX** - Search "animation", "z-index", "accessibility" for common issues -5. **Use stack flag** - Get implementation-specific best practices -6. **Iterate** - If first search doesn't match, try different keywords - ---- - -## Common Rules for Professional UI +- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"`, not just `"app"` +- Try different phrasings for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"` +- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about +- Pass the detected stack explicitly for implementation-specific guidance -These are frequently overlooked issues that make UI look unprofessional: +| Problem | What to Do | +|---------|------------| +| Can't decide on style/color | Re-run `--design-system` with different keywords | +| Dark mode contrast issues | `references/quick-reference.md` §6: `color-dark-mode` + `color-accessible-pairs` | +| Animations feel unnatural | `references/quick-reference.md` §7: `spring-physics` + `easing` + `exit-faster-than-enter` | +| Form UX is poor | `references/quick-reference.md` §8: `inline-validation` + `error-clarity` + `focus-management` | +| Navigation feels confusing | `references/quick-reference.md` §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` | +| Layout breaks on small screens | `references/quick-reference.md` §5: `mobile-first` + `breakpoint-consistency` | +| Performance / jank | `references/quick-reference.md` §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` | -### Icons & Visual Elements - -| Rule | Do | Don't | -|------|----|----- | -| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons | -| **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout | -| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths | -| **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly | - -### Interaction & Cursor - -| Rule | Do | Don't | -|------|----|----- | -| **Cursor pointer** | Add `cursor-pointer` to all clickable/hoverable cards | Leave default cursor on interactive elements | -| **Hover feedback** | Provide visual feedback (color, shadow, border) | No indication element is interactive | -| **Smooth transitions** | Use `transition-colors duration-200` | Instant state changes or too slow (>500ms) | - -### Light/Dark Mode Contrast - -| Rule | Do | Don't | -|------|----|----- | -| **Glass card light mode** | Use `bg-white/80` or higher opacity | Use `bg-white/10` (too transparent) | -| **Text contrast light** | Use `#0F172A` (slate-900) for text | Use `#94A3B8` (slate-400) for body text | -| **Muted text light** | Use `#475569` (slate-600) minimum | Use gray-400 or lighter | -| **Border visibility** | Use `border-gray-200` in light mode | Use `border-white/10` (invisible) | - -### Layout & Spacing - -| Rule | Do | Don't | -|------|----|----- | -| **Floating navbar** | Add `top-4 left-4 right-4` spacing | Stick navbar to `top-0 left-0 right-0` | -| **Content padding** | Account for fixed navbar height | Let content hide behind fixed elements | -| **Consistent max-width** | Use same `max-w-6xl` or `max-w-7xl` | Mix different container widths | - ---- +## Before Delivering App UI -## Pre-Delivery Checklist - -Before delivering UI code, verify these items: - -### Visual Quality -- [ ] No emojis used as icons (use SVG instead) -- [ ] All icons from consistent icon set (Heroicons/Lucide) -- [ ] Brand logos are correct (verified from Simple Icons) -- [ ] Hover states don't cause layout shift -- [ ] Use theme colors directly (bg-primary) not var() wrapper - -### Interaction -- [ ] All clickable elements have `cursor-pointer` -- [ ] Hover states provide clear visual feedback -- [ ] Transitions are smooth (150-300ms) -- [ ] Focus states visible for keyboard navigation - -### Light/Dark Mode -- [ ] Light mode text has sufficient contrast (4.5:1 minimum) -- [ ] Glass/transparent elements visible in light mode -- [ ] Borders visible in both modes -- [ ] Test both modes before delivery - -### Layout -- [ ] Floating elements have proper spacing from edges -- [ ] No content hidden behind fixed navbars -- [ ] Responsive at 375px, 768px, 1024px, 1440px -- [ ] No horizontal scroll on mobile - -### Accessibility -- [ ] All images have alt text -- [ ] Form inputs have labels -- [ ] Color is not the only indicator -- [ ] `prefers-reduced-motion` respected +Read `references/pro-rules.md` and run through its canonical Pre-Delivery Checklist. It covers icon/visual-element discipline, interaction feedback, light/dark contrast, safe-area layout, and accessibility — scoped to native/mobile app UI (iOS/Android/React Native/Flutter). diff --git a/.agents/skills/ui-ux-pro-max/data/app-interface.csv b/.agents/skills/ui-ux-pro-max/data/app-interface.csv new file mode 100644 index 0000000..f34c3cd --- /dev/null +++ b/.agents/skills/ui-ux-pro-max/data/app-interface.csv @@ -0,0 +1,31 @@ +No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity +1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"","",Critical +2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"Email","",Critical +3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"Submit","Submit",High +4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"{status}","{status}",Medium +5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"","",Medium +6,Touch,Touch Target Size,touch 44x44 hitSlop,iOS/Android/React Native,Primary touch targets must be at least 44x44pt,Increase hitSlop or padding to meet minimum,Small icons with tiny touch area,"","",Critical +7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,"","Copying entire ControlTemplate to change one color",Medium,https://platform.uno/docs/articles/external/uno.themes/doc/lightweight-styling.html +24,Styling,Test themes on each platform,Theme rendering differs across platforms,Visual theme testing on all targets,Assuming themes look identical everywhere,"Screenshot comparison across platforms for themed controls","Theming only tested on Windows",Low,https://platform.uno/docs/articles/features/working-with-themes.html +25,Architecture,Use MVVM pattern,Separate view and logic,CommunityToolkit.Mvvm or Prism for MVVM,Code-behind for business logic,"[ObservableProperty] public partial string Title { get; set; } [RelayCommand] private void Save() { }","MainPage.xaml.cs with all logic",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +26,Architecture,Use Uno.Extensions,Official extension libraries for common patterns,Uno.Extensions for DI navigation configuration,Building infrastructure from scratch,"Host.CreateDefaultBuilder().UseNavigation().UseConfiguration()","Manual DI and navigation setup",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/ExtensionsOverview.html +27,Architecture,Use dependency injection,Register services for testability,Microsoft.Extensions.DI through Uno.Extensions,Static service locators and singletons,"services.AddSingleton();","ApiService.Instance or new ApiService() in ViewModels",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Learn/DependencyInjection/DependencyInjectionOverview.html +28,Architecture,Share code via class libraries,Maximize code reuse across targets,Business logic in .NET Standard or shared library,Business logic in platform head projects,"MyApp.Core class library referenced by all heads","Business logic in MyApp.Wasm.csproj",Medium,https://platform.uno/docs/articles/cross-targeted-libraries.html +29,Architecture,Use Uno.Resizetizer for assets,Single source SVG to multi-platform assets,UnoImage for automatic asset generation from SVG,Manual asset export per resolution and platform,"","Manually exporting icon_1x.png icon_2x.png icon_3x.png per platform",Medium,https://platform.uno/docs/articles/external/uno.resizetizer/doc/using-uno-resizetizer.html +30,Accessibility,Set AutomationProperties,Enable screen readers across platforms,AutomationProperties.Name on interactive controls,Controls without accessible names,""," without name",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +31,Accessibility,Test accessibility per platform,Each platform has different assistive tech,Test with VoiceOver TalkBack and Narrator,Testing accessibility on one platform only,"VoiceOver on iOS + TalkBack on Android + Narrator on Windows","Only testing with Narrator on Windows",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +32,Accessibility,Support platform text scaling,Respect user font size preferences,Dynamic font scaling for all text,Fixed font sizes ignoring accessibility,"FontSize=""{ThemeResource BodyTextBlockFontSize}""","FontSize=""14"" everywhere",Medium,https://platform.uno/docs/articles/features/working-with-accessibility.html +33,Testing,Unit test ViewModels,Test business logic independently,xUnit or MSTest on shared ViewModel code,UI testing only,"[Fact] public void LoadData_SetsItems() { vm.Load(); Assert.NotEmpty(vm.Items); }","Manual testing on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +34,Testing,Use Uno.UITest for integration,Cross-platform UI testing framework,Uno.UITest for automated UI tests across platforms,Manual regression testing,"app.WaitForElement(""SaveButton""); app.Tap(""SaveButton"");","Manual click-through on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +35,WASM,Show an extended splash screen on WASM,WASM bundle download and runtime startup take several seconds on first load — render branded UI immediately so users do not see a blank page (AOT and trimming are covered separately),Render a splash overlay in wwwroot/index.html that hides on first XAML navigation,Letting the user wait on a blank white page while the runtime boots,"index.html:
Loading…
hidden via JS interop after first Frame.Navigate","No splash markup in index.html — 5-second blank page on first visit",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +36,WASM,Use AOT compilation for performance,Ahead-of-time compilation improves runtime speed,AOT for production WASM builds,Interpreter mode in production,"InterpreterAndAOT","Default interpreter mode in production deployment",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +37,WASM,Handle browser limitations,WASM runs in browser sandbox,Feature detection for browser APIs,Assuming desktop capabilities in browser,"[JSImport(""globalThis.hasApi"")] static partial bool HasApi(); #if __WASM__ if (HasApi()) { ... } #endif","#if __WASM__ StorageFile.GetFileFromPathAsync(""C:/data"") #endif",Medium,https://platform.uno/docs/articles/platform-specific-csharp.html +38,Controls,Use NavigationView for app shell,WinUI NavigationView for consistent navigation across platforms,NavigationView with MenuItems for app navigation,Custom hamburger menu implementation,"","Custom SplitView with manual toggle button",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/navigationview +39,Controls,Use ContentDialog for modal interactions,Cross-platform modal dialogs using WinUI API,ContentDialog for confirmations and input,Custom overlay Panel as dialog,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/dialogs-and-flyouts/dialogs +40,Controls,Use CommandBar for app actions,Standard command bar with primary and secondary commands,CommandBar with AppBarButtons for toolbar actions,Custom StackPanel toolbar,"","",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +41,Controls,Use ToggleSwitch for boolean settings,Platform-native toggle control for on/off preferences,ToggleSwitch for settings and feature flags,CheckBox for toggle settings,"","",Low,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/toggles +42,Data Binding,Implement INotifyPropertyChanged,Enable UI updates when ViewModel properties change,CommunityToolkit.Mvvm [ObservableProperty] for auto-notification,Properties without change notification,"[ObservableProperty] public partial string Title { get; set; }","public string Title { get; set; } without notification",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +43,Data Binding,Use ObservableCollection for bound lists,Collection change notifications for ItemsSources across platforms,ObservableCollection for data-bound lists,List for bound ItemsSources,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +44,Lifecycle,Handle app suspension on mobile,iOS and Android may suspend or terminate the app — WinAppSDK desktop does not raise Suspending so use window Closed for desktop save-state,Save state in OnSuspending and restore on activation,Ignoring lifecycle losing user state on mobile,"Application.Current.Suspending += (s, e) => { var d = e.SuspendingOperation.GetDeferral(); SaveState(); d.Complete(); };","No suspend handler losing form data on mobile",High,https://platform.uno/docs/articles/features/windows-ui-xaml-application.html +45,Lifecycle,Use Uno.Extensions.Hosting for startup,Structured app initialization with DI and configuration,IHost builder pattern for app startup and service registration,Manual initialization in App constructor,"Host.CreateDefaultBuilder().ConfigureServices(s => s.AddSingleton()).Build();","new MainViewModel() in App.xaml.cs constructor",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Overview/Hosting/HostingOverview.html +46,Performance,Use ListView virtualization for large lists,Only renders visible items to reduce memory and layout cost,ListView with default ItemsStackPanel virtualization,ItemsControl or StackPanel for large data sets," (virtualizes by default)"," rendering 5000 items at once",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/listview-and-gridview +47,Accessibility,Support keyboard navigation on desktop,Skia and WinAppSDK targets need full keyboard operability — note TabIndex routing is not fully implemented on every Uno target,AccessKey and KeyboardAccelerator on Skia and WinAppSDK targets,Mouse-only interactions on desktop,"","Clickable controls without keyboard support on desktop",High,https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-accelerators +48,WASM,Use service workers for offline support,Enable PWA capabilities for WASM deployments,Service worker registration for caching and offline mode,Online-only WASM app with no offline fallback,"manifest.webmanifest","No service worker leaving WASM app unusable offline",Low,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/features-pwa.html +49,Performance,Marshal to UI thread with DispatcherQueue,Cross-thread access to UI elements throws — capture the UI DispatcherQueue once and use TryEnqueue to update from background work,DispatcherQueue.GetForCurrentThread().TryEnqueue from background work,Touching UI controls directly from a Task,"_dispatcher.TryEnqueue(() => StatusText.Text = ""Done"");","await Task.Run(() => StatusText.Text = ""Done""); throws on non-UI thread",High,https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue +50,Styling,Merge XamlControlsResources in App.xaml,Required for Fluent control styles to load — without it controls render with no template,Add XamlControlsResources at the top of Application.Resources MergedDictionaries,Skipping the merged dictionary and wondering why Buttons look unstyled,""," with no XamlControlsResources merged",High,https://platform.uno/docs/articles/features/fluent-styles.html +51,Architecture,Use async [RelayCommand] for I/O,AsyncRelayCommand reports CanExecute=false (raising CanExecuteChanged) and exposes IsRunning while the Task is in flight — the bound control is disabled and re-entrancy is prevented by default (AllowConcurrentExecutions=false),[RelayCommand] on a Task-returning method for awaitable work,async void event handlers calling .Wait() or .Result,"[RelayCommand] private async Task LoadAsync() { Items = await _api.GetAsync(); }","public void OnLoadClick(object s, EventArgs e) { LoadAsync().Wait(); } deadlock risk",Medium,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/generators/relaycommand +52,Architecture,Use x:Uid for localized strings,WinUI x:Uid resolves UI text from .resw resources at runtime — use it instead of hardcoded strings to support localization across iOS Android WASM and desktop from a single project,x:Uid on every user-facing string with matching .resw entries per language under Strings/{lang}/Resources.resw,Hardcoding language-specific strings into XAML or code-behind,"",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +8,Controls,Use ContentDialog for modals,System-styled modal dialogs,ContentDialog for confirmations and input,Custom popup overlays,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/dialogs-and-flyouts/dialogs +9,Controls,Use AutoSuggestBox for search,Built-in search box with suggestions,AutoSuggestBox with QuerySubmitted and SuggestionChosen,TextBox with manual suggestion popup,"","TextBox with custom Popup and ListBox for suggestions",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/auto-suggest-box +10,Controls,Use CalendarDatePicker and TimePicker,Platform-consistent date and time selection,Built-in date and time pickers,Custom date selection controls,"","TextBox with date parsing and validation",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/date-and-time +11,Controls,Use PersonPicture for user avatars,Consistent avatar display with fallback initials,PersonPicture with DisplayName and ProfilePicture,Custom Ellipse with ImageBrush for avatars,"","",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/person-picture +12,Styling,Use ThemeResource for adaptive colors,Colors that switch with light and dark theme,ThemeResource for all color references,Hardcoded hex values that break in dark mode,"Foreground=""{ThemeResource SystemControlForegroundBaseHighBrush}""","Foreground=""#000000""",High,https://learn.microsoft.com/en-us/windows/uwp/design/style/color +13,Styling,Use Fluent Design materials,Acrylic translucent material for depth,Built-in Fluent materials for depth and motion,Custom shader effects for blur and reveal,"","Custom CompositionEffectBrush recreating acrylic",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/style/acrylic +14,Styling,Use Lightweight Styling,Override control resource keys for subtle changes,Lightweight styling resource overrides,Full ControlTemplate copy for small tweaks,"","Entire ControlTemplate copied to change background",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles#lightweight-styling +15,Styling,Use implicit styles for consistency,TargetType without x:Key applies to all instances,Implicit Style for default control appearance,Repeating Setters on every control instance,"","CornerRadius=""4"" on every Button in the page",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles +16,Styling,Use VisualStateManager for visual states,Define visual states with Setters that change properties when triggered,VisualStateGroup containing VisualStates with Setter targets,Toggling Visibility from code-behind on SizeChanged,"","SizeChanged handler that flips Orientation in code-behind",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +17,Navigation,Use Frame for page navigation,Windows.UI.Xaml.Controls.Frame for UWP page navigation,Frame.Navigate with typed parameters,Swapping UserControls manually,"rootFrame.Navigate(typeof(DetailPage), itemId);","contentArea.Content = new DetailPage();",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/basics/navigate-between-two-pages +18,Navigation,Handle back button correctly,Provide an in-app Back button styled with NavigationBackButtonNormalStyle and handle SystemNavigationManager.BackRequested for hardware back gamepad B and Tablet-Mode back; also handle CoreDispatcher.AcceleratorKeyActivated for Alt+Left,In-app NavigationBackButtonNormalStyle button plus SystemNavigationManager.BackRequested handler,Relying on the deprecated title-bar back button (AppViewBackButtonVisibility) or ignoring system back signals,"SystemNavigationManager.GetForCurrentView().BackRequested += OnBackRequested;","No back button support on phone or tablet",High,https://learn.microsoft.com/en-us/windows/uwp/ui-input/back-navigation +19,Navigation,Support deep linking with protocol activation,Respond to URI activation and toast taps,OnActivated handler with proper page routing,Ignoring activation arguments,"protected override void OnActivated(IActivatedEventArgs args) { if (args.Kind == ActivationKind.Protocol) { ... } }","Empty OnActivated ignoring URI parameters",Medium,https://learn.microsoft.com/en-us/windows/uwp/launch-resume/handle-uri-activation +20,Navigation,Use ConnectedAnimations for continuity,Smooth transitions between pages,ConnectedAnimationService for shared element transitions,Abrupt page transitions with no visual continuity,"ConnectedAnimationService.GetForCurrentView().PrepareToAnimate(""image"", sourceImage);","No transition animation between list and detail",Low,https://learn.microsoft.com/en-us/windows/uwp/design/motion/connected-animation +21,Data Binding,Implement INotifyPropertyChanged,Enable UI updates on property changes,INotifyPropertyChanged on all ViewModels,Auto-properties without notification,"public string Title { get => _title; set { _title = value; OnPropertyChanged(); } }","public string Title { get; set; } expecting UI updates",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +22,Data Binding,Use ObservableCollection for lists,Collection change notifications for ItemsSources,ObservableCollection for bound lists,List for data-bound collections,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +23,Data Binding,Use function bindings with x:Bind,Call static methods directly in markup,x:Bind to static converter methods,IValueConverter for trivial transforms,"","Full IValueConverter class for bool to Visibility",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/function-bindings +24,Data Binding,Specify Mode on x:Bind,x:Bind defaults to OneTime not OneWay,Mode=OneWay or TwoWay when live updates needed,Omitting Mode and getting stale UI,"Text=""{x:Bind Title, Mode=OneWay}""","Text=""{x:Bind Title}"" expecting live updates",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +25,Data Binding,Use CollectionViewSource for grouping,Group and sort collections declaratively,CollectionViewSource for grouped ListView and GridView,Manual grouping logic in code-behind,"","Manual loop building grouped StackPanels",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +26,Performance,Use ListView and GridView virtualization,Only creates containers for visible items,Default virtualization in ListView and GridView,Setting ItemsPanel to non-virtualizing panel," (virtualizes by default)","",High,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview +27,Performance,Use ISupportIncrementalLoading,Load data on demand as user scrolls,ISupportIncrementalLoading for large datasets,Loading entire collection upfront,"class IncrementalSource : ObservableCollection, ISupportIncrementalLoading","await LoadAll() loading 50K items at startup",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +28,Performance,Reduce XAML visual tree depth,Simpler trees layout and render faster,Flat templates with minimal nesting,Deeply nested panels in DataTemplates," in item template","... 8 levels in item template",Medium,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-xaml-loading +29,Performance,Use compiled bindings in DataTemplates,x:Bind in templates requires x:DataType,x:DataType on DataTemplate for compiled bindings,{Binding} in item templates for large lists,"","",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +30,Performance,Profile with Visual Studio diagnostics,Measure before optimizing,Application Timeline and Memory Usage tools,Guessing at performance problems,"VS Diagnostic Tools > Application Timeline","Optimizing without profiling data",Medium,https://learn.microsoft.com/en-us/visualstudio/profiling/application-timeline +31,Threading,Use async/await for all IO,Keep UI thread responsive,async/await for file network and database operations,Synchronous IO blocking the UI thread,"var file = await StorageFile.GetFileFromPathAsync(path);","StorageFile.GetFileFromPathAsync(path).AsTask().Result;",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +32,Threading,Use CoreDispatcher for UI thread access,Post work back to the UI thread from background,Dispatcher.RunAsync from background threads,Touching UI elements from background threads,"await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => Status = ""Done"");","textBlock.Text = ""Done"" from Task.Run",High,https://learn.microsoft.com/en-us/uwp/api/windows.ui.core.coredispatcher +33,Threading,Offload CPU work with Task.Run,Keep compute-heavy work off UI thread,Task.Run for CPU-bound operations,Heavy computation blocking UI,"var result = await Task.Run(() => ProcessData(items));","var result = ProcessData(items); freezing UI",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +34,Threading,Use IProgress for status updates,Report progress from background operations,IProgress for progress reporting to UI,Polling shared variables for progress,"var progress = new Progress(p => ProgressBar.Value = p); await Task.Run(() => Process(progress));","while (!done) { await Task.Delay(100); check shared field; }",Medium,https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 +35,Adaptive,Use AdaptiveTrigger for responsive layouts,MinWindowWidth and MinWindowHeight triggers fire at standard breakpoints (640 small / 1008 medium),AdaptiveTrigger inside VisualState.StateTriggers with the 640 and 1008 breakpoints,Fixed layouts for a single screen size,"","Single-column layout at all widths",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +36,Adaptive,Design for multiple device families,Phone tablet desktop Xbox and HoloLens,DeviceFamily-specific views and resources,Desktop-only design ignoring other form factors,"DeviceFamily-Mobile/MainPage.xaml for phone-specific layout","Fixed 1920x1080 layout",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/layout/screen-sizes-and-breakpoints-for-responsive-design +37,Adaptive,Use RelativePanel for adaptive positioning,Controls position relative to each other,RelativePanel for layouts that reflow at breakpoints,Absolute positioning or fixed margins,"","Copying entire ControlTemplate to change one color",Medium,https://platform.uno/docs/articles/external/uno.themes/doc/lightweight-styling.html +24,Styling,Test themes on each platform,Theme rendering differs across platforms,Visual theme testing on all targets,Assuming themes look identical everywhere,"Screenshot comparison across platforms for themed controls","Theming only tested on Windows",Low,https://platform.uno/docs/articles/features/working-with-themes.html +25,Architecture,Use MVVM pattern,Separate view and logic,CommunityToolkit.Mvvm or Prism for MVVM,Code-behind for business logic,"[ObservableProperty] public partial string Title { get; set; } [RelayCommand] private void Save() { }","MainPage.xaml.cs with all logic",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +26,Architecture,Use Uno.Extensions,Official extension libraries for common patterns,Uno.Extensions for DI navigation configuration,Building infrastructure from scratch,"Host.CreateDefaultBuilder().UseNavigation().UseConfiguration()","Manual DI and navigation setup",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/ExtensionsOverview.html +27,Architecture,Use dependency injection,Register services for testability,Microsoft.Extensions.DI through Uno.Extensions,Static service locators and singletons,"services.AddSingleton();","ApiService.Instance or new ApiService() in ViewModels",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Learn/DependencyInjection/DependencyInjectionOverview.html +28,Architecture,Share code via class libraries,Maximize code reuse across targets,Business logic in .NET Standard or shared library,Business logic in platform head projects,"MyApp.Core class library referenced by all heads","Business logic in MyApp.Wasm.csproj",Medium,https://platform.uno/docs/articles/cross-targeted-libraries.html +29,Architecture,Use Uno.Resizetizer for assets,Single source SVG to multi-platform assets,UnoImage for automatic asset generation from SVG,Manual asset export per resolution and platform,"","Manually exporting icon_1x.png icon_2x.png icon_3x.png per platform",Medium,https://platform.uno/docs/articles/external/uno.resizetizer/doc/using-uno-resizetizer.html +30,Accessibility,Set AutomationProperties,Enable screen readers across platforms,AutomationProperties.Name on interactive controls,Controls without accessible names,""," without name",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +31,Accessibility,Test accessibility per platform,Each platform has different assistive tech,Test with VoiceOver TalkBack and Narrator,Testing accessibility on one platform only,"VoiceOver on iOS + TalkBack on Android + Narrator on Windows","Only testing with Narrator on Windows",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +32,Accessibility,Support platform text scaling,Respect user font size preferences,Dynamic font scaling for all text,Fixed font sizes ignoring accessibility,"FontSize=""{ThemeResource BodyTextBlockFontSize}""","FontSize=""14"" everywhere",Medium,https://platform.uno/docs/articles/features/working-with-accessibility.html +33,Testing,Unit test ViewModels,Test business logic independently,xUnit or MSTest on shared ViewModel code,UI testing only,"[Fact] public void LoadData_SetsItems() { vm.Load(); Assert.NotEmpty(vm.Items); }","Manual testing on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +34,Testing,Use Uno.UITest for integration,Cross-platform UI testing framework,Uno.UITest for automated UI tests across platforms,Manual regression testing,"app.WaitForElement(""SaveButton""); app.Tap(""SaveButton"");","Manual click-through on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +35,WASM,Show an extended splash screen on WASM,WASM bundle download and runtime startup take several seconds on first load — render branded UI immediately so users do not see a blank page (AOT and trimming are covered separately),Render a splash overlay in wwwroot/index.html that hides on first XAML navigation,Letting the user wait on a blank white page while the runtime boots,"index.html:
Loading…
hidden via JS interop after first Frame.Navigate","No splash markup in index.html — 5-second blank page on first visit",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +36,WASM,Use AOT compilation for performance,Ahead-of-time compilation improves runtime speed,AOT for production WASM builds,Interpreter mode in production,"InterpreterAndAOT","Default interpreter mode in production deployment",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +37,WASM,Handle browser limitations,WASM runs in browser sandbox,Feature detection for browser APIs,Assuming desktop capabilities in browser,"[JSImport(""globalThis.hasApi"")] static partial bool HasApi(); #if __WASM__ if (HasApi()) { ... } #endif","#if __WASM__ StorageFile.GetFileFromPathAsync(""C:/data"") #endif",Medium,https://platform.uno/docs/articles/platform-specific-csharp.html +38,Controls,Use NavigationView for app shell,WinUI NavigationView for consistent navigation across platforms,NavigationView with MenuItems for app navigation,Custom hamburger menu implementation,"","Custom SplitView with manual toggle button",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/navigationview +39,Controls,Use ContentDialog for modal interactions,Cross-platform modal dialogs using WinUI API,ContentDialog for confirmations and input,Custom overlay Panel as dialog,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/dialogs-and-flyouts/dialogs +40,Controls,Use CommandBar for app actions,Standard command bar with primary and secondary commands,CommandBar with AppBarButtons for toolbar actions,Custom StackPanel toolbar,"","",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +41,Controls,Use ToggleSwitch for boolean settings,Platform-native toggle control for on/off preferences,ToggleSwitch for settings and feature flags,CheckBox for toggle settings,"","",Low,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/toggles +42,Data Binding,Implement INotifyPropertyChanged,Enable UI updates when ViewModel properties change,CommunityToolkit.Mvvm [ObservableProperty] for auto-notification,Properties without change notification,"[ObservableProperty] public partial string Title { get; set; }","public string Title { get; set; } without notification",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +43,Data Binding,Use ObservableCollection for bound lists,Collection change notifications for ItemsSources across platforms,ObservableCollection for data-bound lists,List for bound ItemsSources,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +44,Lifecycle,Handle app suspension on mobile,iOS and Android may suspend or terminate the app — WinAppSDK desktop does not raise Suspending so use window Closed for desktop save-state,Save state in OnSuspending and restore on activation,Ignoring lifecycle losing user state on mobile,"Application.Current.Suspending += (s, e) => { var d = e.SuspendingOperation.GetDeferral(); SaveState(); d.Complete(); };","No suspend handler losing form data on mobile",High,https://platform.uno/docs/articles/features/windows-ui-xaml-application.html +45,Lifecycle,Use Uno.Extensions.Hosting for startup,Structured app initialization with DI and configuration,IHost builder pattern for app startup and service registration,Manual initialization in App constructor,"Host.CreateDefaultBuilder().ConfigureServices(s => s.AddSingleton()).Build();","new MainViewModel() in App.xaml.cs constructor",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Overview/Hosting/HostingOverview.html +46,Performance,Use ListView virtualization for large lists,Only renders visible items to reduce memory and layout cost,ListView with default ItemsStackPanel virtualization,ItemsControl or StackPanel for large data sets," (virtualizes by default)"," rendering 5000 items at once",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/listview-and-gridview +47,Accessibility,Support keyboard navigation on desktop,Skia and WinAppSDK targets need full keyboard operability — note TabIndex routing is not fully implemented on every Uno target,AccessKey and KeyboardAccelerator on Skia and WinAppSDK targets,Mouse-only interactions on desktop,"","Clickable controls without keyboard support on desktop",High,https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-accelerators +48,WASM,Use service workers for offline support,Enable PWA capabilities for WASM deployments,Service worker registration for caching and offline mode,Online-only WASM app with no offline fallback,"manifest.webmanifest","No service worker leaving WASM app unusable offline",Low,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/features-pwa.html +49,Performance,Marshal to UI thread with DispatcherQueue,Cross-thread access to UI elements throws — capture the UI DispatcherQueue once and use TryEnqueue to update from background work,DispatcherQueue.GetForCurrentThread().TryEnqueue from background work,Touching UI controls directly from a Task,"_dispatcher.TryEnqueue(() => StatusText.Text = ""Done"");","await Task.Run(() => StatusText.Text = ""Done""); throws on non-UI thread",High,https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue +50,Styling,Merge XamlControlsResources in App.xaml,Required for Fluent control styles to load — without it controls render with no template,Add XamlControlsResources at the top of Application.Resources MergedDictionaries,Skipping the merged dictionary and wondering why Buttons look unstyled,""," with no XamlControlsResources merged",High,https://platform.uno/docs/articles/features/fluent-styles.html +51,Architecture,Use async [RelayCommand] for I/O,AsyncRelayCommand reports CanExecute=false (raising CanExecuteChanged) and exposes IsRunning while the Task is in flight — the bound control is disabled and re-entrancy is prevented by default (AllowConcurrentExecutions=false),[RelayCommand] on a Task-returning method for awaitable work,async void event handlers calling .Wait() or .Result,"[RelayCommand] private async Task LoadAsync() { Items = await _api.GetAsync(); }","public void OnLoadClick(object s, EventArgs e) { LoadAsync().Wait(); } deadlock risk",Medium,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/generators/relaycommand +52,Architecture,Use x:Uid for localized strings,WinUI x:Uid resolves UI text from .resw resources at runtime — use it instead of hardcoded strings to support localization across iOS Android WASM and desktop from a single project,x:Uid on every user-facing string with matching .resw entries per language under Strings/{lang}/Resources.resw,Hardcoding language-specific strings into XAML or code-behind,"",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +8,Controls,Use ContentDialog for modals,System-styled modal dialogs,ContentDialog for confirmations and input,Custom popup overlays,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/dialogs-and-flyouts/dialogs +9,Controls,Use AutoSuggestBox for search,Built-in search box with suggestions,AutoSuggestBox with QuerySubmitted and SuggestionChosen,TextBox with manual suggestion popup,"","TextBox with custom Popup and ListBox for suggestions",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/auto-suggest-box +10,Controls,Use CalendarDatePicker and TimePicker,Platform-consistent date and time selection,Built-in date and time pickers,Custom date selection controls,"","TextBox with date parsing and validation",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/date-and-time +11,Controls,Use PersonPicture for user avatars,Consistent avatar display with fallback initials,PersonPicture with DisplayName and ProfilePicture,Custom Ellipse with ImageBrush for avatars,"","",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/person-picture +12,Styling,Use ThemeResource for adaptive colors,Colors that switch with light and dark theme,ThemeResource for all color references,Hardcoded hex values that break in dark mode,"Foreground=""{ThemeResource SystemControlForegroundBaseHighBrush}""","Foreground=""#000000""",High,https://learn.microsoft.com/en-us/windows/uwp/design/style/color +13,Styling,Use Fluent Design materials,Acrylic translucent material for depth,Built-in Fluent materials for depth and motion,Custom shader effects for blur and reveal,"","Custom CompositionEffectBrush recreating acrylic",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/style/acrylic +14,Styling,Use Lightweight Styling,Override control resource keys for subtle changes,Lightweight styling resource overrides,Full ControlTemplate copy for small tweaks,"","Entire ControlTemplate copied to change background",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles#lightweight-styling +15,Styling,Use implicit styles for consistency,TargetType without x:Key applies to all instances,Implicit Style for default control appearance,Repeating Setters on every control instance,"","CornerRadius=""4"" on every Button in the page",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles +16,Styling,Use VisualStateManager for visual states,Define visual states with Setters that change properties when triggered,VisualStateGroup containing VisualStates with Setter targets,Toggling Visibility from code-behind on SizeChanged,"","SizeChanged handler that flips Orientation in code-behind",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +17,Navigation,Use Frame for page navigation,Windows.UI.Xaml.Controls.Frame for UWP page navigation,Frame.Navigate with typed parameters,Swapping UserControls manually,"rootFrame.Navigate(typeof(DetailPage), itemId);","contentArea.Content = new DetailPage();",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/basics/navigate-between-two-pages +18,Navigation,Handle back button correctly,Provide an in-app Back button styled with NavigationBackButtonNormalStyle and handle SystemNavigationManager.BackRequested for hardware back gamepad B and Tablet-Mode back; also handle CoreDispatcher.AcceleratorKeyActivated for Alt+Left,In-app NavigationBackButtonNormalStyle button plus SystemNavigationManager.BackRequested handler,Relying on the deprecated title-bar back button (AppViewBackButtonVisibility) or ignoring system back signals,"SystemNavigationManager.GetForCurrentView().BackRequested += OnBackRequested;","No back button support on phone or tablet",High,https://learn.microsoft.com/en-us/windows/uwp/ui-input/back-navigation +19,Navigation,Support deep linking with protocol activation,Respond to URI activation and toast taps,OnActivated handler with proper page routing,Ignoring activation arguments,"protected override void OnActivated(IActivatedEventArgs args) { if (args.Kind == ActivationKind.Protocol) { ... } }","Empty OnActivated ignoring URI parameters",Medium,https://learn.microsoft.com/en-us/windows/uwp/launch-resume/handle-uri-activation +20,Navigation,Use ConnectedAnimations for continuity,Smooth transitions between pages,ConnectedAnimationService for shared element transitions,Abrupt page transitions with no visual continuity,"ConnectedAnimationService.GetForCurrentView().PrepareToAnimate(""image"", sourceImage);","No transition animation between list and detail",Low,https://learn.microsoft.com/en-us/windows/uwp/design/motion/connected-animation +21,Data Binding,Implement INotifyPropertyChanged,Enable UI updates on property changes,INotifyPropertyChanged on all ViewModels,Auto-properties without notification,"public string Title { get => _title; set { _title = value; OnPropertyChanged(); } }","public string Title { get; set; } expecting UI updates",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +22,Data Binding,Use ObservableCollection for lists,Collection change notifications for ItemsSources,ObservableCollection for bound lists,List for data-bound collections,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +23,Data Binding,Use function bindings with x:Bind,Call static methods directly in markup,x:Bind to static converter methods,IValueConverter for trivial transforms,"","Full IValueConverter class for bool to Visibility",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/function-bindings +24,Data Binding,Specify Mode on x:Bind,x:Bind defaults to OneTime not OneWay,Mode=OneWay or TwoWay when live updates needed,Omitting Mode and getting stale UI,"Text=""{x:Bind Title, Mode=OneWay}""","Text=""{x:Bind Title}"" expecting live updates",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +25,Data Binding,Use CollectionViewSource for grouping,Group and sort collections declaratively,CollectionViewSource for grouped ListView and GridView,Manual grouping logic in code-behind,"","Manual loop building grouped StackPanels",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +26,Performance,Use ListView and GridView virtualization,Only creates containers for visible items,Default virtualization in ListView and GridView,Setting ItemsPanel to non-virtualizing panel," (virtualizes by default)","",High,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview +27,Performance,Use ISupportIncrementalLoading,Load data on demand as user scrolls,ISupportIncrementalLoading for large datasets,Loading entire collection upfront,"class IncrementalSource : ObservableCollection, ISupportIncrementalLoading","await LoadAll() loading 50K items at startup",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +28,Performance,Reduce XAML visual tree depth,Simpler trees layout and render faster,Flat templates with minimal nesting,Deeply nested panels in DataTemplates," in item template","... 8 levels in item template",Medium,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-xaml-loading +29,Performance,Use compiled bindings in DataTemplates,x:Bind in templates requires x:DataType,x:DataType on DataTemplate for compiled bindings,{Binding} in item templates for large lists,"","",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +30,Performance,Profile with Visual Studio diagnostics,Measure before optimizing,Application Timeline and Memory Usage tools,Guessing at performance problems,"VS Diagnostic Tools > Application Timeline","Optimizing without profiling data",Medium,https://learn.microsoft.com/en-us/visualstudio/profiling/application-timeline +31,Threading,Use async/await for all IO,Keep UI thread responsive,async/await for file network and database operations,Synchronous IO blocking the UI thread,"var file = await StorageFile.GetFileFromPathAsync(path);","StorageFile.GetFileFromPathAsync(path).AsTask().Result;",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +32,Threading,Use CoreDispatcher for UI thread access,Post work back to the UI thread from background,Dispatcher.RunAsync from background threads,Touching UI elements from background threads,"await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => Status = ""Done"");","textBlock.Text = ""Done"" from Task.Run",High,https://learn.microsoft.com/en-us/uwp/api/windows.ui.core.coredispatcher +33,Threading,Offload CPU work with Task.Run,Keep compute-heavy work off UI thread,Task.Run for CPU-bound operations,Heavy computation blocking UI,"var result = await Task.Run(() => ProcessData(items));","var result = ProcessData(items); freezing UI",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +34,Threading,Use IProgress for status updates,Report progress from background operations,IProgress for progress reporting to UI,Polling shared variables for progress,"var progress = new Progress(p => ProgressBar.Value = p); await Task.Run(() => Process(progress));","while (!done) { await Task.Delay(100); check shared field; }",Medium,https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 +35,Adaptive,Use AdaptiveTrigger for responsive layouts,MinWindowWidth and MinWindowHeight triggers fire at standard breakpoints (640 small / 1008 medium),AdaptiveTrigger inside VisualState.StateTriggers with the 640 and 1008 breakpoints,Fixed layouts for a single screen size,"","Single-column layout at all widths",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +36,Adaptive,Design for multiple device families,Phone tablet desktop Xbox and HoloLens,DeviceFamily-specific views and resources,Desktop-only design ignoring other form factors,"DeviceFamily-Mobile/MainPage.xaml for phone-specific layout","Fixed 1920x1080 layout",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/layout/screen-sizes-and-breakpoints-for-responsive-design +37,Adaptive,Use RelativePanel for adaptive positioning,Controls position relative to each other,RelativePanel for layouts that reflow at breakpoints,Absolute positioning or fixed margins,"","Copying entire ControlTemplate to change one color",Medium,https://platform.uno/docs/articles/external/uno.themes/doc/lightweight-styling.html +24,Styling,Test themes on each platform,Theme rendering differs across platforms,Visual theme testing on all targets,Assuming themes look identical everywhere,"Screenshot comparison across platforms for themed controls","Theming only tested on Windows",Low,https://platform.uno/docs/articles/features/working-with-themes.html +25,Architecture,Use MVVM pattern,Separate view and logic,CommunityToolkit.Mvvm or Prism for MVVM,Code-behind for business logic,"[ObservableProperty] public partial string Title { get; set; } [RelayCommand] private void Save() { }","MainPage.xaml.cs with all logic",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +26,Architecture,Use Uno.Extensions,Official extension libraries for common patterns,Uno.Extensions for DI navigation configuration,Building infrastructure from scratch,"Host.CreateDefaultBuilder().UseNavigation().UseConfiguration()","Manual DI and navigation setup",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/ExtensionsOverview.html +27,Architecture,Use dependency injection,Register services for testability,Microsoft.Extensions.DI through Uno.Extensions,Static service locators and singletons,"services.AddSingleton();","ApiService.Instance or new ApiService() in ViewModels",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Learn/DependencyInjection/DependencyInjectionOverview.html +28,Architecture,Share code via class libraries,Maximize code reuse across targets,Business logic in .NET Standard or shared library,Business logic in platform head projects,"MyApp.Core class library referenced by all heads","Business logic in MyApp.Wasm.csproj",Medium,https://platform.uno/docs/articles/cross-targeted-libraries.html +29,Architecture,Use Uno.Resizetizer for assets,Single source SVG to multi-platform assets,UnoImage for automatic asset generation from SVG,Manual asset export per resolution and platform,"","Manually exporting icon_1x.png icon_2x.png icon_3x.png per platform",Medium,https://platform.uno/docs/articles/external/uno.resizetizer/doc/using-uno-resizetizer.html +30,Accessibility,Set AutomationProperties,Enable screen readers across platforms,AutomationProperties.Name on interactive controls,Controls without accessible names,""," without name",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +31,Accessibility,Test accessibility per platform,Each platform has different assistive tech,Test with VoiceOver TalkBack and Narrator,Testing accessibility on one platform only,"VoiceOver on iOS + TalkBack on Android + Narrator on Windows","Only testing with Narrator on Windows",High,https://platform.uno/docs/articles/features/working-with-accessibility.html +32,Accessibility,Support platform text scaling,Respect user font size preferences,Dynamic font scaling for all text,Fixed font sizes ignoring accessibility,"FontSize=""{ThemeResource BodyTextBlockFontSize}""","FontSize=""14"" everywhere",Medium,https://platform.uno/docs/articles/features/working-with-accessibility.html +33,Testing,Unit test ViewModels,Test business logic independently,xUnit or MSTest on shared ViewModel code,UI testing only,"[Fact] public void LoadData_SetsItems() { vm.Load(); Assert.NotEmpty(vm.Items); }","Manual testing on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +34,Testing,Use Uno.UITest for integration,Cross-platform UI testing framework,Uno.UITest for automated UI tests across platforms,Manual regression testing,"app.WaitForElement(""SaveButton""); app.Tap(""SaveButton"");","Manual click-through on each platform",Medium,https://platform.uno/docs/articles/external/uno.uitest/doc/using-uno-uitest.html +35,WASM,Show an extended splash screen on WASM,WASM bundle download and runtime startup take several seconds on first load — render branded UI immediately so users do not see a blank page (AOT and trimming are covered separately),Render a splash overlay in wwwroot/index.html that hides on first XAML navigation,Letting the user wait on a blank white page while the runtime boots,"index.html:
Loading…
hidden via JS interop after first Frame.Navigate","No splash markup in index.html — 5-second blank page on first visit",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +36,WASM,Use AOT compilation for performance,Ahead-of-time compilation improves runtime speed,AOT for production WASM builds,Interpreter mode in production,"InterpreterAndAOT","Default interpreter mode in production deployment",Medium,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/runtime-execution-modes.html +37,WASM,Handle browser limitations,WASM runs in browser sandbox,Feature detection for browser APIs,Assuming desktop capabilities in browser,"[JSImport(""globalThis.hasApi"")] static partial bool HasApi(); #if __WASM__ if (HasApi()) { ... } #endif","#if __WASM__ StorageFile.GetFileFromPathAsync(""C:/data"") #endif",Medium,https://platform.uno/docs/articles/platform-specific-csharp.html +38,Controls,Use NavigationView for app shell,WinUI NavigationView for consistent navigation across platforms,NavigationView with MenuItems for app navigation,Custom hamburger menu implementation,"","Custom SplitView with manual toggle button",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/navigationview +39,Controls,Use ContentDialog for modal interactions,Cross-platform modal dialogs using WinUI API,ContentDialog for confirmations and input,Custom overlay Panel as dialog,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/dialogs-and-flyouts/dialogs +40,Controls,Use CommandBar for app actions,Standard command bar with primary and secondary commands,CommandBar with AppBarButtons for toolbar actions,Custom StackPanel toolbar,"","",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +41,Controls,Use ToggleSwitch for boolean settings,Platform-native toggle control for on/off preferences,ToggleSwitch for settings and feature flags,CheckBox for toggle settings,"","",Low,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/toggles +42,Data Binding,Implement INotifyPropertyChanged,Enable UI updates when ViewModel properties change,CommunityToolkit.Mvvm [ObservableProperty] for auto-notification,Properties without change notification,"[ObservableProperty] public partial string Title { get; set; }","public string Title { get; set; } without notification",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +43,Data Binding,Use ObservableCollection for bound lists,Collection change notifications for ItemsSources across platforms,ObservableCollection for data-bound lists,List for bound ItemsSources,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/ +44,Lifecycle,Handle app suspension on mobile,iOS and Android may suspend or terminate the app — WinAppSDK desktop does not raise Suspending so use window Closed for desktop save-state,Save state in OnSuspending and restore on activation,Ignoring lifecycle losing user state on mobile,"Application.Current.Suspending += (s, e) => { var d = e.SuspendingOperation.GetDeferral(); SaveState(); d.Complete(); };","No suspend handler losing form data on mobile",High,https://platform.uno/docs/articles/features/windows-ui-xaml-application.html +45,Lifecycle,Use Uno.Extensions.Hosting for startup,Structured app initialization with DI and configuration,IHost builder pattern for app startup and service registration,Manual initialization in App constructor,"Host.CreateDefaultBuilder().ConfigureServices(s => s.AddSingleton()).Build();","new MainViewModel() in App.xaml.cs constructor",Medium,https://platform.uno/docs/articles/external/uno.extensions/doc/Overview/Hosting/HostingOverview.html +46,Performance,Use ListView virtualization for large lists,Only renders visible items to reduce memory and layout cost,ListView with default ItemsStackPanel virtualization,ItemsControl or StackPanel for large data sets," (virtualizes by default)"," rendering 5000 items at once",High,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/listview-and-gridview +47,Accessibility,Support keyboard navigation on desktop,Skia and WinAppSDK targets need full keyboard operability — note TabIndex routing is not fully implemented on every Uno target,AccessKey and KeyboardAccelerator on Skia and WinAppSDK targets,Mouse-only interactions on desktop,"","Clickable controls without keyboard support on desktop",High,https://learn.microsoft.com/en-us/windows/apps/develop/input/keyboard-accelerators +48,WASM,Use service workers for offline support,Enable PWA capabilities for WASM deployments,Service worker registration for caching and offline mode,Online-only WASM app with no offline fallback,"manifest.webmanifest","No service worker leaving WASM app unusable offline",Low,https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/features-pwa.html +49,Performance,Marshal to UI thread with DispatcherQueue,Cross-thread access to UI elements throws — capture the UI DispatcherQueue once and use TryEnqueue to update from background work,DispatcherQueue.GetForCurrentThread().TryEnqueue from background work,Touching UI controls directly from a Task,"_dispatcher.TryEnqueue(() => StatusText.Text = ""Done"");","await Task.Run(() => StatusText.Text = ""Done""); throws on non-UI thread",High,https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue +50,Styling,Merge XamlControlsResources in App.xaml,Required for Fluent control styles to load — without it controls render with no template,Add XamlControlsResources at the top of Application.Resources MergedDictionaries,Skipping the merged dictionary and wondering why Buttons look unstyled,""," with no XamlControlsResources merged",High,https://platform.uno/docs/articles/features/fluent-styles.html +51,Architecture,Use async [RelayCommand] for I/O,AsyncRelayCommand reports CanExecute=false (raising CanExecuteChanged) and exposes IsRunning while the Task is in flight — the bound control is disabled and re-entrancy is prevented by default (AllowConcurrentExecutions=false),[RelayCommand] on a Task-returning method for awaitable work,async void event handlers calling .Wait() or .Result,"[RelayCommand] private async Task LoadAsync() { Items = await _api.GetAsync(); }","public void OnLoadClick(object s, EventArgs e) { LoadAsync().Wait(); } deadlock risk",Medium,https://learn.microsoft.com/en-us/dotnet/communitytoolkit/mvvm/generators/relaycommand +52,Architecture,Use x:Uid for localized strings,WinUI x:Uid resolves UI text from .resw resources at runtime — use it instead of hardcoded strings to support localization across iOS Android WASM and desktop from a single project,x:Uid on every user-facing string with matching .resw entries per language under Strings/{lang}/Resources.resw,Hardcoding language-specific strings into XAML or code-behind,"",Medium,https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/command-bar +8,Controls,Use ContentDialog for modals,System-styled modal dialogs,ContentDialog for confirmations and input,Custom popup overlays,"","Grid overlay with manual focus trapping",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/dialogs-and-flyouts/dialogs +9,Controls,Use AutoSuggestBox for search,Built-in search box with suggestions,AutoSuggestBox with QuerySubmitted and SuggestionChosen,TextBox with manual suggestion popup,"","TextBox with custom Popup and ListBox for suggestions",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/auto-suggest-box +10,Controls,Use CalendarDatePicker and TimePicker,Platform-consistent date and time selection,Built-in date and time pickers,Custom date selection controls,"","TextBox with date parsing and validation",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/date-and-time +11,Controls,Use PersonPicture for user avatars,Consistent avatar display with fallback initials,PersonPicture with DisplayName and ProfilePicture,Custom Ellipse with ImageBrush for avatars,"","",Low,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/person-picture +12,Styling,Use ThemeResource for adaptive colors,Colors that switch with light and dark theme,ThemeResource for all color references,Hardcoded hex values that break in dark mode,"Foreground=""{ThemeResource SystemControlForegroundBaseHighBrush}""","Foreground=""#000000""",High,https://learn.microsoft.com/en-us/windows/uwp/design/style/color +13,Styling,Use Fluent Design materials,Acrylic translucent material for depth,Built-in Fluent materials for depth and motion,Custom shader effects for blur and reveal,"","Custom CompositionEffectBrush recreating acrylic",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/style/acrylic +14,Styling,Use Lightweight Styling,Override control resource keys for subtle changes,Lightweight styling resource overrides,Full ControlTemplate copy for small tweaks,"","Entire ControlTemplate copied to change background",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles#lightweight-styling +15,Styling,Use implicit styles for consistency,TargetType without x:Key applies to all instances,Implicit Style for default control appearance,Repeating Setters on every control instance,"","CornerRadius=""4"" on every Button in the page",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/controls-and-patterns/xaml-styles +16,Styling,Use VisualStateManager for visual states,Define visual states with Setters that change properties when triggered,VisualStateGroup containing VisualStates with Setter targets,Toggling Visibility from code-behind on SizeChanged,"","SizeChanged handler that flips Orientation in code-behind",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +17,Navigation,Use Frame for page navigation,Windows.UI.Xaml.Controls.Frame for UWP page navigation,Frame.Navigate with typed parameters,Swapping UserControls manually,"rootFrame.Navigate(typeof(DetailPage), itemId);","contentArea.Content = new DetailPage();",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/basics/navigate-between-two-pages +18,Navigation,Handle back button correctly,Provide an in-app Back button styled with NavigationBackButtonNormalStyle and handle SystemNavigationManager.BackRequested for hardware back gamepad B and Tablet-Mode back; also handle CoreDispatcher.AcceleratorKeyActivated for Alt+Left,In-app NavigationBackButtonNormalStyle button plus SystemNavigationManager.BackRequested handler,Relying on the deprecated title-bar back button (AppViewBackButtonVisibility) or ignoring system back signals,"SystemNavigationManager.GetForCurrentView().BackRequested += OnBackRequested;","No back button support on phone or tablet",High,https://learn.microsoft.com/en-us/windows/uwp/ui-input/back-navigation +19,Navigation,Support deep linking with protocol activation,Respond to URI activation and toast taps,OnActivated handler with proper page routing,Ignoring activation arguments,"protected override void OnActivated(IActivatedEventArgs args) { if (args.Kind == ActivationKind.Protocol) { ... } }","Empty OnActivated ignoring URI parameters",Medium,https://learn.microsoft.com/en-us/windows/uwp/launch-resume/handle-uri-activation +20,Navigation,Use ConnectedAnimations for continuity,Smooth transitions between pages,ConnectedAnimationService for shared element transitions,Abrupt page transitions with no visual continuity,"ConnectedAnimationService.GetForCurrentView().PrepareToAnimate(""image"", sourceImage);","No transition animation between list and detail",Low,https://learn.microsoft.com/en-us/windows/uwp/design/motion/connected-animation +21,Data Binding,Implement INotifyPropertyChanged,Enable UI updates on property changes,INotifyPropertyChanged on all ViewModels,Auto-properties without notification,"public string Title { get => _title; set { _title = value; OnPropertyChanged(); } }","public string Title { get; set; } expecting UI updates",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +22,Data Binding,Use ObservableCollection for lists,Collection change notifications for ItemsSources,ObservableCollection for bound lists,List for data-bound collections,"ObservableCollection Items { get; } = new();","List Items { get; set; } = new();",High,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +23,Data Binding,Use function bindings with x:Bind,Call static methods directly in markup,x:Bind to static converter methods,IValueConverter for trivial transforms,"","Full IValueConverter class for bool to Visibility",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/function-bindings +24,Data Binding,Specify Mode on x:Bind,x:Bind defaults to OneTime not OneWay,Mode=OneWay or TwoWay when live updates needed,Omitting Mode and getting stale UI,"Text=""{x:Bind Title, Mode=OneWay}""","Text=""{x:Bind Title}"" expecting live updates",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +25,Data Binding,Use CollectionViewSource for grouping,Group and sort collections declaratively,CollectionViewSource for grouped ListView and GridView,Manual grouping logic in code-behind,"","Manual loop building grouped StackPanels",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +26,Performance,Use ListView and GridView virtualization,Only creates containers for visible items,Default virtualization in ListView and GridView,Setting ItemsPanel to non-virtualizing panel," (virtualizes by default)","",High,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-gridview-and-listview +27,Performance,Use ISupportIncrementalLoading,Load data on demand as user scrolls,ISupportIncrementalLoading for large datasets,Loading entire collection upfront,"class IncrementalSource : ObservableCollection, ISupportIncrementalLoading","await LoadAll() loading 50K items at startup",Medium,https://learn.microsoft.com/en-us/windows/uwp/data-binding/data-binding-in-depth +28,Performance,Reduce XAML visual tree depth,Simpler trees layout and render faster,Flat templates with minimal nesting,Deeply nested panels in DataTemplates," in item template","... 8 levels in item template",Medium,https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/optimize-xaml-loading +29,Performance,Use compiled bindings in DataTemplates,x:Bind in templates requires x:DataType,x:DataType on DataTemplate for compiled bindings,{Binding} in item templates for large lists,"","",High,https://learn.microsoft.com/en-us/windows/uwp/xaml-platform/x-bind-markup-extension +30,Performance,Profile with Visual Studio diagnostics,Measure before optimizing,Application Timeline and Memory Usage tools,Guessing at performance problems,"VS Diagnostic Tools > Application Timeline","Optimizing without profiling data",Medium,https://learn.microsoft.com/en-us/visualstudio/profiling/application-timeline +31,Threading,Use async/await for all IO,Keep UI thread responsive,async/await for file network and database operations,Synchronous IO blocking the UI thread,"var file = await StorageFile.GetFileFromPathAsync(path);","StorageFile.GetFileFromPathAsync(path).AsTask().Result;",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +32,Threading,Use CoreDispatcher for UI thread access,Post work back to the UI thread from background,Dispatcher.RunAsync from background threads,Touching UI elements from background threads,"await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => Status = ""Done"");","textBlock.Text = ""Done"" from Task.Run",High,https://learn.microsoft.com/en-us/uwp/api/windows.ui.core.coredispatcher +33,Threading,Offload CPU work with Task.Run,Keep compute-heavy work off UI thread,Task.Run for CPU-bound operations,Heavy computation blocking UI,"var result = await Task.Run(() => ProcessData(items));","var result = ProcessData(items); freezing UI",High,https://learn.microsoft.com/en-us/windows/uwp/threading-async/asynchronous-programming-universal-windows-platform-apps +34,Threading,Use IProgress for status updates,Report progress from background operations,IProgress for progress reporting to UI,Polling shared variables for progress,"var progress = new Progress(p => ProgressBar.Value = p); await Task.Run(() => Process(progress));","while (!done) { await Task.Delay(100); check shared field; }",Medium,https://learn.microsoft.com/en-us/dotnet/api/system.progress-1 +35,Adaptive,Use AdaptiveTrigger for responsive layouts,MinWindowWidth and MinWindowHeight triggers fire at standard breakpoints (640 small / 1008 medium),AdaptiveTrigger inside VisualState.StateTriggers with the 640 and 1008 breakpoints,Fixed layouts for a single screen size,"","Single-column layout at all widths",High,https://learn.microsoft.com/en-us/windows/uwp/design/layout/layouts-with-xaml +36,Adaptive,Design for multiple device families,Phone tablet desktop Xbox and HoloLens,DeviceFamily-specific views and resources,Desktop-only design ignoring other form factors,"DeviceFamily-Mobile/MainPage.xaml for phone-specific layout","Fixed 1920x1080 layout",Medium,https://learn.microsoft.com/en-us/windows/uwp/design/layout/screen-sizes-and-breakpoints-for-responsive-design +37,Adaptive,Use RelativePanel for adaptive positioning,Controls position relative to each other,RelativePanel for layouts that reflow at breakpoints,Absolute positioning or fixed margins,"