uno

Flowery.Uno MANDATORY Development Notes

This file captures learnings and patterns discovered during Flowery.Uno development for future reference.

🚨 READ THIS FIRST (top crash-prevention rules)

If you only read the first ~50 lines of this file, read this section. These rules prevent the most common Uno “mystery” runtime crashes:

• ContentControls that rebuild Content: ALWAYS detach before re-parenting.
  • Pattern: _userContent = Content; Content = null; BuildVisualTree(); _presenter.Content = _userContent;
  • See “UIElement can only have one parent” (search for ### 19).
• Never bind a ContentPresenter back to this.Content in a control that later sets Content = _rootGrid (creates self-parenting / re-parenting issues).
  • See the anti-pattern example under ### 19.
• Don’t use PathIcon dynamically in code-behind (Uno can throw ArgumentException: Value does not fall within the expected range.).
  • Use Microsoft.UI.Xaml.Shapes.Path or Flowery.Helpers.FloweryPathHelpers instead (search for ### 18).
• Use DaisyControlExtensions.Icon for button icons - This is the GOLD STANDARD (see section below).
• Ambiguous type names: Path, Color, etc. often need aliasing/qualification.
  • Example: using Path = Microsoft.UI.Xaml.Shapes.Path; (search for ### 12).
• Do NOT merge ms-appx:///uno.toolkit.*/Styles/Generic.xaml.
  • Uno.Toolkit.* packages do not ship Styles/Generic.xaml. Adding that dictionary will fail to load resources and can crash at startup. ShadowContainer only needs the package reference.

Neumorphic Takeaways

For the distilled, field-tested fixes and integration notes from recent stability work, see llms-static/neumorphic.md → Field-Tested Integration Notes (Session Takeaways).

ThemeShadow + Elevation Learnings

• ThemeShadow requires explicit receivers: add the receiver to ThemeShadow.Receivers (see Uno tests in !uno/src/SamplesApp/UITests.Shared/Windows_UI_Xaml_Media/ThemeShadowTests).
• Translation.Z defines shadow depth: the casting element must have a Translation Z (e.g., 0,0,6).
• CornerRadius is respected when ThemeShadow is applied directly to Border or Rectangle with radius properties (no custom masking required).
• WASM/Skia elevation: for rounded shadows, apply SetElevation to the template’s Border (e.g., ButtonBorder), not the Button control itself.