0.8.0.5

docs/PLUGIN_SDK_V4_MIGRATION.md

@@ -44,6 +44,91 @@ public MyWidget(PluginDesktopComponentContext context)
 }
 ```
 
+## Corner Radius System
+
+Plugin widgets must follow the host's corner radius settings to maintain visual consistency with built-in components.
+
+### Why Plugins Cannot Use XAML Resources
+
+Plugins run in a separate `AssemblyLoadContext` and cannot directly access the host's resource dictionary. Therefore, `{DynamicResource DesignCornerRadiusComponent}` is not available in plugin XAML. Instead, plugins must resolve corner radius values in code through `PluginDesktopComponentContext`.
+
+### Available Corner Radius Presets
+
+| Preset | Default Value | Usage |
+|--------|---------------|-------|
+| `Micro` | 6px | Tiny elements |
+| `Xs` | 12px | Small elements and icon containers |
+| `Sm` | 14px | Small colored blocks |
+| `Md` | 20px | Common buttons/cards |
+| `Lg` | 28px | Normal glass panels |
+| `Xl` | 32px | Emphasized containers |
+| `Island` | 36px | Large containers |
+| `Component` | 18px | **Desktop widget standard radius** |
+| `Default` | (adaptive) | Adaptive based on cell size |
+
+### Corner Radius API Reference
+
+```csharp
+public class MyWidget : Border
+{
+    public MyWidget(PluginDesktopComponentContext context)
+    {
+        // Method 1: Use preset tokens (recommended for consistency)
+        CornerRadius = context.ResolveCornerRadius(PluginCornerRadiusPreset.Component);
+        
+        // Method 2: Use preset with fallback (extension method)
+        CornerRadius = context.Appearance.Snapshot.ResolveCornerRadius(
+            PluginCornerRadiusPreset.Md, 
+            fallback: new CornerRadius(8));
+        
+        // Method 3: Custom radius with global scale applied
+        CornerRadius = context.ResolveScaledCornerRadius(baseRadius: 16, minimum: 8, maximum: 24);
+        
+        // Method 4: Access tokens directly
+        var tokens = context.CornerRadiusTokens;
+        CornerRadius = tokens.ToCornerRadius(PluginCornerRadiusPreset.Md);
+        
+        // Method 5: Get raw token value (double)
+        double componentRadius = context.CornerRadiusTokens.Component;
+    }
+}
+```
+
+### Best Practices
+
+1. **Always use `PluginCornerRadiusPreset.Component` for the widget root container** - This ensures consistency with built-in widgets.
+
+2. **Apply corner radius in code, not XAML** - Since plugins cannot access host resources, set `CornerRadius` in the constructor or code-behind.
+
+3. **Re-apply radius on size changes** - For adaptive layouts, subscribe to `SizeChanged` and recalculate:
+
+```csharp
+public MyWidget(PluginDesktopComponentContext context)
+{
+    _context = context;
+    ApplyCornerRadius();
+    SizeChanged += (_, _) => ApplyCornerRadius();
+}
+
+private void ApplyCornerRadius()
+{
+    var basis = Math.Min(Bounds.Width, Bounds.Height);
+    CornerRadius = _context.ResolveCornerRadius(
+        PluginCornerRadiusPreset.Component,
+        minimum: Math.Clamp(basis * 0.08, 8, 16),
+        maximum: Math.Clamp(basis * 0.15, 16, 28));
+}
+```
+
+4. **Inner elements can use smaller presets** - For cards or buttons inside your widget:
+
+```csharp
+var innerCard = new Border
+{
+    CornerRadius = _context.ResolveCornerRadius(PluginCornerRadiusPreset.Md)
+};
+```
+
 ## Manifest Update
 
 Update plugin manifests to API `4.x`: