syncfusion-wpf-ui-builder

# Syncfusion WPF UI Builder ## Overview The **Syncfusion WPF UI Builder** skill is a desktop-only WPF control generator that orchestrates an AI agent through 8 stages to generate production-ready UI controls powered by Syncfusion. ## What This Skill Does **✅ Generates (UI Layer):** - WPF XAML using Syncfusion controls + C# code-behind with MVVM pattern - UI Automation accessibility markup (WCAG 2.1 AA) - DPI-aware responsive layouts - Client-side input validation and event handling **✅ Generates (Backend Layer):** - Service classes with business logic (e.g., `AuthService`, `CustomerService`) - Repository interfaces and in-memory implementations - Navigation / screen-transition logic - Data models, DTOs, and ViewModel interfaces **❌ Does NOT Generate:** - Real database schemas, ORM migrations, or SQL - Live third-party API integrations - Authentication infrastructure (OAuth, JWT issuing) - Environment secrets beyond `SYNCFUSION_LICENSE_KEY` > **Full-feature rule:** Every generated screen must be end-to-end functional — UI wired to backend logic, validation active, and navigation working. Partial logic or stub-only output is not acceptable. --- ## Quick Start ### Prerequisites 1. WPF project targeting .NET Framework 4.6.2+ or .NET 8+ 2. Visual Studio 2022+ with WPF workload 3. Syncfusion WPF library (auto-installed if missing): ```bash dotnet add package Syncfusion.SfGrid.WPF ``` 4. Node.js 14+ (required for Stage 3 BM25 control-mapping script) ### Examples **Login Form** ``` User: "Create a login form with email, password, and remember me checkbox" Output: ✓ Views/LoginForm/LoginForm.xaml — SfTextInputLayout + SfButton ✓ Views/LoginForm/LoginForm.xaml.cs — event handling, navigation on success ✓ ViewModels/LoginViewModel.cs — INotifyPropertyChanged, ICommand ✓ Services/AuthService.cs — credential validation logic ✓ Models/LoginModel.cs — email, password, rememberMe fields ``` **Customer Data Table** ``` User: "Build a customer data table with sorting and filtering" Output: ✓ Views/CustomerTable/CustomerTable.xaml — SfDataGrid with sort/filter ✓ ViewModels/CustomerTableViewModel.cs — ObservableCollection, filter logic ✓ Services/CustomerService.cs — data retrieval, search logic ✓ Models/CustomerModel.cs — typed model with sample data ``` --- ## Reusable Workflow Instructions ### Key Architecture | Property | Detail | |----------|--------| | Design | Stateless — conversation history is sole state store | | Stages | 8 total (6 automated, 2 user-gated) | | User gates | Stage 3 (control confirmation) + Stage 4 (theming) | | Auto-healing | Stages 5A, 5B, 6A, 7 auto-fix errors before passing downstream | | Hard block | Stage 2A blocks on WPF/WinUI framework mismatch | | Code scope | Both UI and backend generated together as one complete feature | ### Stage Execution Flow (Mandatory Order) ``` User Request ↓ [Stage 1] Intent Analysis → Parse query, identify control type & features, resolve ambiguities → Identify backend requirements (services, validation, navigation) implied by the screen → Read: references/stage-1-intent-analysis.md → Output: Control type + modifiers + target directory + backend scope summary ↓ [Stage 2] Project Detection → Auto-detect framework, .NET version, theming, project structure → Detect existing service/repository patterns to match generated backend style → Read: references/stage-2-project-detection.md → Output: Project config + user confirmation (with override option) ↓ [Stage 2A] Framework Consistency Guard ⛔ FAIL-FAST → Enforce WPF namespace: xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" → BLOCK if WPF/WinUI controls or namespaces are mixed → Output: Confirmed namespace declarations or halt with mismatch report ↓ [Stage 3] Layout Analysis & Control Mapping ⭐ USER GATE #1 + SCRIPT REQUIRED → Read: references/stage-3-layout-analysis.md → Read control-mapping.json to identify: • Relevant Syncfusion controls for each UI element • Associated skill reference files per control → Run BM25 script: node controls_search.cjs <project-root>/control-mapping.json (cd <project-root>\.apm\skills\syncfusion-wpf-ui-builder\scripts first) → Map backend actions to each control (e.g., ButtonAdv[Login] → AuthService.ValidateAsync) → Output: control-mapping.json + Syncfusion control map + backend action map + user confirmation ↓ [Stage 4] Theming & Design System ⭐ USER GATE #2 → Read: references/stage-4-theming-and-design-system.md → Lock: Syncfusion theme, hex color system, 4pt DIP grid spacing, 1.25 type ratio → Select: Material / Fluent / custom XAML theme → Output: Design tokens confirmed; locked before any code generation ↓ [Stage — Control Skill Extraction] Control Skill Extraction 🔴 BLOCKING PRE-REQUISITE — Before Code Generation → Validate: ALL controls in control-mapping.json have validation='✓ VERIFIED' (score > 10) → For each control: Read skill file → Extract namespace, NuGet package, properties, events → Persist to: <project-root>/skill-extraction.json with validation_status="PASS" → Halt if: Skill file missing OR namespace/package/properties incomplete → Output: skill-extraction.json (pre-validated control metadata for Stage 5 code generation) ↓ [Stage 5B-1] Type Safety Enforcement 🔒 CRITICAL — runs BEFORE XAML generation → Validate Background → must be Brush type (SolidColorBrush, LinearGradientBrush, etc.) → Validate Margin → must be "double,double,double,double" → Validate FontSize → must be double > 0 → Validate Width/Height → must be double > 0 or Auto → Validate Colors → must be #AARRGGBB or named color → Auto-fix: Replace invalid values with safe defaults ↓ [Stage 5B-2] Resource Validation 🔒 CRITICAL — runs BEFORE XAML generation → Scan all {StaticResource X} and {DynamicResource X} in XAML → Verify each key X exists in merged ResourceDictionary → Auto-inject missing keys with fallback values (e.g., SolidColorBrush #FF000000) → Check for duplicate x:Key values ↓ [Stage 5] Safe Code Generation 🔒 COMPLETE IMPLEMENTATION — UI + BACKEND **Prerequisite:** skill-extraction.json exists with validation_status="PASS" (from Stage — Control Skill Extraction) **Data source:** All namespaces/properties/events/packages from skill-extraction.json (never guessed) **Pre-Generation Analysis (Mandatory):** → Read: references/stage-5-code-generation.md → Read control-mapping.json FIRST → identify all Syncfusion controls, events, commands → Read corresponding Syncfusion skill file → extract required properties & behaviors → Map XAML controls ↔ control-mapping.json ↔ skill directives for alignment **Code Generation Principles (Strict Adherence):** → Generate ONLY methods, properties, events explicitly required by mapped controls → No generic boilerplate, utility methods, or unused stub code → Preserve existing codebase structure; avoid overwriting unrelated members → Tight alignment: every control + event + binding traces back to skill directive **UI Generation (Complete Implementation):** → XAML: all Syncfusion namespaces, all mapped controls, all event bindings per skill → .xaml.cs: full event handler implementations, DataContext binding, all using statements → ViewModel: ALL bound properties (INotifyPropertyChanged), ALL ICommand bindings (RelayCommand) **Backend Generation (Skill-Driven):** → Service classes: implement only business logic declared in control map + skill file → Repository + in-memory data: only if skill directives require data access → Navigation: open/close windows per skill success/failure paths → Validation: required fields + format checks per skill specification → Error propagation: surface errors from service → ViewModel → XAML display **Functional Completeness & Safety:** → Every control must be fully wired to backend logic (no dead buttons or stub properties) → Output: complete, compilable, tested code — zero missing implementations → Constraints: no overwritten code, no unused members, minimal-but-full functionality ↓ [Stage 6] NuGet Dependency Management → Read: references/stage-6-dependencies.md → Detect required Syncfusion WPF + theme NuGet packages → Verify all XAML Syncfusion namespaces have corresponding packages → Output: dotnet add command(s) or auto-install ↓ [Stage 7] XAML Dry-Run Validation → Read: references/stage-7-validation.md + assets/validation-rules.md → Simulate XamlReader.Parse() on generated XAML → Auto-fix: invalid tags, missing namespaces, type mismatches → Loop until parse succeeds (max 5 iterations) → Abort on: circular reference, unsupported control type, licensing error → Output: PASS ✓ or FAIL ✗ ↓ [Stage 8] Code Insertion → Insert all validated files (UI + backend) into project → Update project references, verify build → STOP on errors; report all inserted file paths on success ↓ ✓ Complete ``` ### Stage Gate Summary | Stage | Interaction | Behavior | |-------|-------------|----------| | 1–2 | Auto-detect | Auto-flow | | 2A | Framework check | ⛔ BLOCK on mismatch | | 3 | Control + backend action confirmation | ⭐ User gate | | 4 | Theming confirmation | ⭐ User gate | | **5A** | **Skill extraction + validation** | **⛔ BLOCK if file missing or extraction fails** | | 5B-1–5B-2 | Property + resource validation | Auto-fix | | 5 | UI + backend code generation + skill alignment | Auto-flow (only if Stage — Control Skill Extraction passed) | | 6 | Dependency validation gate | ⛔ BLOCK if skill-extraction.json missing | | 6–6A | Dependency + binding + service validation | Auto-fix / Fail gate | | 7 | XAML dry-run validation | Auto-fix loop | | 8 | Code insertion + build verification | Auto-flow | --- ## Agent Instructions 1. **Validate scope**: Confirm request is for a WPF screen. Generate both UI and backend together — never UI alone. 2. **Stage — Control Skill Extraction is mandatory**: Before ANY code generation, execute Stage — Control Skill Extraction (Control Skill Extraction). Halt if skill-extraction.json cannot be created or validated. 3. **Read control-mapping.json before Stage 5**: Identify which controls appear, which events fire, and which backend actions are implied. Generate only what those controls need. 4. **Follow stage order strictly**: Never skip or reorder stages. Stage — Control Skill Extraction must complete before Stage 5 (code generation). 5. **Load references on-demand**: Read each stage's `.md` file immediately before executing that stage. 6. **Stateless execution**: Read all prior decisions from conversation context at each stage start. 7. **License key handling**: - Check for `SYNCFUSION_LICENSE_KEY` in `appsettings.json` or environment - If missing, prompt: *"Get a free Community License at https://www.syncfusion.com/account/manage-trials"* - If provided, inject into `appsettings.json` + call `registerLicense()` in app init - If skipped, warn that a watermark will appear --- ## Code Generation Rules (Mandatory) ### ⛔ Stage — Control Skill Extraction Prerequisite (CRITICAL) - **Before ANY code generation in Stage 5**: Execute Stage — Control Skill Extraction - Confirm `skill-extraction.json` exists with `validation_status: "PASS"` - **All code generation must use data from `skill-extraction.json`** (namespaces, properties, events, packages) - ❌ Never guess or assume APIs; ❌ Never infer package names - ✅ All control metadata must be pre-extracted and verified ### Control-Mapping-Driven Generation - **Before generating any code**, read `control-mapping.json` to identify: - Every Syncfusion control required by the screen - The associated skill reference file for each control - The backend action (service method) mapped to each interactive control - Generate **only** the methods, properties, commands, and events that are directly required by the mapped controls in XAML - Do not add unrelated utility methods, extra services, or placeholder code not tied to a mapped control ### Minimal-but-Complete Rule Every generated file must be: - **Context-aware**: driven by the specific skill and its control map, not a generic template - **Feature-complete**: all controls in XAML are fully wired to logic (no dead buttons or unbound fields) - **Minimal**: no boilerplate beyond what the mapped controls require ### Screen Completeness Checklist Before finalizing Stage 5 output, verify each screen satisfies: | Requirement | Example (Login Screen) | |-------------|------------------------| | Input handling | Email → `SfTextInputLayout`, Password → `PasswordBox` bound to ViewModel properties | | Client-side validation | Required field check, email regex, password min-length | | Event handling | Login `ButtonAdv` → `LoginCommand.Execute` → `AuthService.ValidateCredentials` | | Backend logic | `AuthService.ValidateCredentials(email, password)` returns success/failure | | Navigation on success | Opens `DashboardWindow`, closes `LoginWindow` | | Error display | Failure message shown via `MessageBox` or inline `SfTextInputLayout` error hint | | Server-side validation | `AuthService` rejects empty or malformed inputs independently of UI | --- ## Boundary Rules (Critical) | Rule | Detail | |------|--------| | UI + backend together | Always generate both layers as one complete feature; never UI-only | | Syncfusion controls only | Use only Syncfusion WPF controls; never native MS controls (TextBox → `SfTextInputLayout`, Button → `ButtonAdv`, ComboBox → `ComboBoxAdv`, DataGrid → `SfDataGrid`, MessageBox → `MessageBox`, ProgressBar → `SfLinearProgressBar`, TreeView → `SfTreeView`, TabControl → `SfTabControl`, Calendar → `CalendarEdit`, DatePicker → `SfDatePicker`, TimePicker → `SfTimePicker`) | | Skill file + control-mapping.json first | **Mandatory pre-generation:** Read the Syncfusion skill file to extract required properties, behaviors, and constraints BEFORE any code generation in Stage 5. Cross-reference with control-mapping.json to ensure all controls, events, and backend actions align with skill directives. | | Dependency rule: Skill files ONLY | **Before adding ANY NuGet package:** (1) Read skill file, (2) Extract exact package name, (3) Use latest stable version, (4) Never assume/infer names. Only packages documented in skill files are permitted. Reject all others. | | Mock data only | Use in-memory repositories with sample data; no live DB or real API calls | | No secrets | Only `SYNCFUSION_LICENSE_KEY` when user explicitly provides it | | Minimal-but-complete | Generate exactly what the mapped controls need — no extra boilerplate | | Compilation guaranteed | Stage 6A must pass ALL checks (UI + backend) before any file is inserted | | Framework purity | Never mix WPF and WinUI controls or namespaces in same project | --- ## DO ✅ / DON'T ❌ Guidelines **DO:** - ✅ Read the Syncfusion skill file FIRST to identify required properties, behaviors, and constraints - ✅ Read `control-mapping.json` SECOND to identify mapped controls, events, and backend actions - ✅ Cross-reference skill file + control-mapping.json + XAML for tight alignment before any code generation - ✅ Generate both UI and backend in Stage 5 as a single cohesive output - ✅ Implement full event handler logic (login → validate → navigate), never stubs - ✅ Wire every control in XAML to a ViewModel property, command, or event handler - ✅ Use `MessageBox` for dialogs, `SfTextInputLayout` for text inputs, `ButtonAdv` for buttons - ✅ Use `SfDataGrid` for all tabular data; never native `DataGrid` - ✅ Lock design tokens in Stage 4 before generating any code in Stage 5 - ✅ Run the BM25 `controls_search.cjs` script in Stage 3 - ✅ Apply `AutomationProperties` for all interactive controls - ✅ Use `SfSkinManager` for theme application - ✅ Use relative layouts (Grid/StackPanel); never hardcode widths for responsive areas **DON'T:** - ❌ Generate code without reading the Syncfusion skill file first - ❌ Skip reading both skill file AND `control-mapping.json` before Stage 5 - ❌ Generate UI without the corresponding backend service and navigation logic - ❌ Use native MS controls (`TextBox`, `Button`, `ComboBox`, `DataGrid`, `MessageBox`, etc.) - ❌ Generate code not directly required by mapped controls or skill directives (no unused helpers or empty stubs) - ❌ Skip Stage 2A framework guard - ❌ Generate XAML before Stage — Control Skill Extraction/5B validation passes - ❌ Insert code before Stage 6A compilation gate passes - ❌ Use `dynamic` types without explicit justification - ❌ Hardcode secrets in XAML or code-behind --- ## Error Handling & Validation **Per-stage recovery:** 1. Retry once with same approach 2. If retry fails → apply workaround or skip to next stage 3. Notify user with error message 4. Offer: *"Would you like to go back to Stage 3 and choose a different layout?"* 5. Reference `references/Build.md` for common errors **Compilation fail gate (Stage 6A):** - Missing event handler → HALT, regenerate Stage 5 - Missing binding property → HALT, regenerate Stage 5 - Missing service method called from ViewModel → HALT, regenerate Stage 5 - Missing `using` statement → HALT, regenerate Stage 5 **XAML parse loop (Stage 7):** - Max 5 auto-fix iterations - Abort on: circular reference, unsupported control, licensing error --- ## ⛔ MANDATORY ERROR HANDLING PROTOCOL **If ANY build error or validation failure occurs:** ### Issue 1 & 3: Theme / Resource Errors **Errors:** `MC3072: Property 'BorderBrush' does not exist...` or `ResourceDictionary.DeferrableContent exception` - ✅ **Fix:** Stage 4 + Stage 7 - ✅ Apply Syncfusion theme ONLY via `SfSkinManager.SetTheme(this, new Theme("<LockedThemeName>"))` in Window constructor - ✅ Set `SfSkinManager.ApplyStylesOnApplication = true` in `App.xaml.cs` `OnStartup()` - ❌ NEVER merge Syncfusion theme ResourceDictionaries manually into `Application.Resources` - ✅ Custom resources ONLY: `Themes/Colors.xaml`, `Themes/Spacing.xaml`, `Themes/Typography.xaml` ### Issue 2: Missing Syncfusion Control **Error:** `'SfTextInputLayout' does not exist in namespace...` - ✅ **Fix:** Stage 6 (Dependencies) - ✅ Read `control-mapping.json` → identify mapped control - ✅ Read skill file (`syncfusion-wpf-[control]/SKILL.md`) → extract exact NuGet package name - ✅ Install package: latest stable version matching Stage 2 version - ❌ NEVER assume or infer package names ### Critical Rule: ALWAYS Read Skill Files First **If build fails OR control error occurs:** 1. ✅ Refer back to control's skill file FIRST 2. ✅ Verify: API names, namespace declarations, NuGet package version 3. ❌ DO NOT fallback automatically to Microsoft/WPF default controls (e.g., `TextBox`, `ComboBox`) 4. ⛔ HALT if skill file missing or ambiguous — no silent corrections 5. ✅ Retry build with skill-verified changes before next stage --- ## Resource Loading Strategy (Mandatory) Load files **on-demand only** — never preload all references. | When | Load | |------|------| | Before Stage 1 | `references/stage-1-intent-analysis.md` | | Before Stage 2 | `references/stage-2-project-detection.md` | | Before Stage 3 | `references/stage-3-layout-analysis.md` | | Before Stage 4 | `references/stage-4-theming-and-design-system.md` |