reactor-design

# Windows 11 Design for Reactor Author, review, and fix Reactor UI code following Windows 11 design system rules. Reactor is a functional UI framework for WinUI 3 that builds UI entirely in C# — no XAML, no data binding, no ViewModels. UI is described with immutable Element records, composed via bare factory methods imported with `using static Microsoft.UI.Reactor.Factories` (`TextBlock(...)`, `VStack(...)`, etc.), and updated through a React-style reconciler with hooks (`UseState`, `UseEffect`, etc.). > **Controlled prop note:** when design examples use inputs such as > `TextBox(value, setValue)` or `Slider(value, ...)`, the factory keeps the > simple call-site shape. Direct element-record reads of controlled props now > return `Optional<T>`; use `.GetValueOrDefault(...)` or `.Value`. See > [`migration/050-optional-t.md`](../../../../docs/guide/migration/050-optional-t.md). This skill translates the Windows 11 design language into Reactor's C# projection so that apps built with Reactor look, feel, and behave like first-class Windows 11 applications. ## Workflow 1. Author new Reactor UI using the rules below. 2. Review a PR using the checklist at the end of this file. 3. Fix feedback by mapping issues to the specific rule and applying the correct pattern. 4. Verify changes using the testing guidance. ## Quick Scan Checklist Check these areas early in every review: - Theme tokens used for all colors — no hardcoded hex strings for themed surfaces. - High Contrast works — no opacity, no accent colors, only system color brushes. - Typography uses `Heading()`, `SubHeading()`, `Caption()`, or WinUI style tokens — not raw `FontSize`/`FontWeight`. - Layout values use the 4px grid. - Text scaling and localization are safe — no fixed heights on text containers. - Shadows have elevation (`Translation(0, 0, 32)`). - Acrylic surfaces use correct background + border pairings. - `AutomationName()` set on icon-only controls. - Keys set on list items for stable reconciliation. ## Core Rules (Always Apply) ### 1. Theming Is the Primary Lens Use `Theme.*` tokens for all colors and brushes. Never hardcode hex colors for themed surfaces. ```csharp // Correct: theme tokens TextBlock("Hello").Foreground(Theme.PrimaryText) Border(child).Background(Theme.CardBackground) Button("Action").Background(Theme.Accent) // Wrong: hardcoded colors on themed surfaces TextBlock("Hello").Foreground("#000000") Border(child).Background("#FFFFFF") ``` Hardcoded colors are acceptable only for: - One-off decorative elements that intentionally ignore theming (e.g., brand logos) - Explicit hit-test targets (`Background("#00000000")` for transparent hit areas) #### Theme Token Reference > ⚠️ **`Theme.Error`, `Theme.Success`, `Theme.Warning`, `Theme.ErrorText` do NOT exist.** > Use `Theme.SystemCritical` (red/error), `Theme.SystemSuccess` (green), `Theme.SystemCaution` (yellow). **Text:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.PrimaryText` | `TextFillColorPrimaryBrush` | Primary body text, titles, and labels | | `Theme.SecondaryText` | `TextFillColorSecondaryBrush` | Captions, subtitles, and supplementary info | | `Theme.TertiaryText` | `TextFillColorTertiaryBrush` | Placeholder text and disabled secondary content | | `Theme.DisabledText` | `TextFillColorDisabledBrush` | Text in disabled controls or inactive states | | `Theme.AccentText` | `AccentTextFillColorPrimaryBrush` | Hyperlinks, accent-colored labels, and interactive text | **Accent fill:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.Accent` | `AccentFillColorDefaultBrush` | Primary accent buttons and controls at rest | | `Theme.AccentSecondary` | `AccentFillColorSecondaryBrush` | Accent button hover state | | `Theme.AccentTertiary` | `AccentFillColorTertiaryBrush` | Accent button pressed state | | `Theme.AccentDisabled` | `AccentFillColorDisabledBrush` | Disabled accent controls | **Control fill:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.ControlFill` | `ControlFillColorDefaultBrush` | Default rest state for standard controls | | `Theme.ControlFillSecondary` | `ControlFillColorSecondaryBrush` | Hover state of standard controls | | `Theme.ControlFillTertiary` | `ControlFillColorTertiaryBrush` | Pressed state of standard controls | | `Theme.ControlFillDisabled` | `ControlFillColorDisabledBrush` | Disabled state of standard controls | | `Theme.ControlFillInputActive` | `ControlFillColorInputActiveBrush` | Active/focused text input field backgrounds | **Surfaces & backgrounds:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.SolidBackground` | `SolidBackgroundFillColorBaseBrush` | App and page-level background (base layer) | | `Theme.CardBackground` | `CardBackgroundFillColorDefaultBrush` | Card and elevated surface backgrounds | | `Theme.LayerFill` | `LayerFillColorDefaultBrush` | Flyout, dialog, and pane backgrounds | | `Theme.SubtleFill` | `SubtleFillColorSecondaryBrush` | Subtle control highlights and section backgrounds | | `Theme.SmokeFill` | `SmokeFillColorDefaultBrush` | Semi-transparent overlay behind modal dialogs | **Stroke & border:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.CardStroke` | `CardStrokeColorDefaultBrush` | Borders on cards and elevated containers | | `Theme.SurfaceStroke` | `SurfaceStrokeColorDefaultBrush` | Borders on flyouts, dialogs, and pane surfaces | | `Theme.DividerStroke` | `DividerStrokeColorDefaultBrush` | Horizontal or vertical dividers between content | | `Theme.ControlStroke` | `ControlStrokeColorDefaultBrush` | Borders on interactive controls at rest | | `Theme.ControlStrokeSecondary` | `ControlStrokeColorSecondaryBrush` | Bottom edge of controls for depth effect | **System signal:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.SystemAttention` | `SystemFillColorAttentionBrush` | Informational indicators and badges | | `Theme.SystemSuccess` | `SystemFillColorSuccessBrush` | Success states and confirmations | | `Theme.SystemCaution` | `SystemFillColorCautionBrush` | Warning states and cautionary indicators | | `Theme.SystemCritical` | `SystemFillColorCriticalBrush` | Error states and critical alerts | | `Theme.SystemNeutral` | `SystemFillColorNeutralBrush` | Neutral status indicators | | `Theme.SystemSolidNeutral` | `SystemFillColorSolidNeutralBrush` | Solid neutral fill for icons and non-text indicators | **System signal backgrounds:** | Token | WinUI Resource | Purpose | |-------|---------------|---------| | `Theme.SystemAttentionBackground` | `SystemFillColorAttentionBackgroundBrush` | Background for attention/info banners | | `Theme.SystemSuccessBackground` | `SystemFillColorSuccessBackgroundBrush` | Background for success banners and info bars | | `Theme.SystemCautionBackground` | `SystemFillColorCautionBackgroundBrush` | Background for warning banners and info bars | | `Theme.SystemCriticalBackground` | `SystemFillColorCriticalBackgroundBrush` | Background for error banners and info bars | | `Theme.SystemNeutralBackground` | `SystemFillColorNeutralBackgroundBrush` | Background for neutral status banners | | `Theme.SystemSolidAttention` | `SystemFillColorSolidAttentionBackgroundBrush` | Solid background for high-contrast attention surfaces | For any WinUI resource not exposed as a named token, use `Theme.Ref("ResourceKeyBrush")`. #### Custom Theme Resource References ```csharp // Reference any WinUI resource by key Border(child).Background(Theme.Ref("AcrylicBackgroundFillColorDefaultBrush")) Border(child).WithBorder(Theme.Ref("SurfaceStrokeColorFlyoutBrush"), 1) ``` #### Per-Subtree Theme Override Force a subtree to a specific theme variant: ```csharp // Sidebar always renders in dark theme VStack(sidebarContent).RequestedTheme(ElementTheme.Dark) ``` See [theme-aware-resources.md](design-docs/theme-aware-resources.md) for full token list and pairing rules. ### 2. Lightweight Styling (Per-Control Resource Overrides) Override control template resources using `.Resources()` to customize visual states without replacing the entire template: ```csharp // Correct: override button resources for a subtle button Button("Action", onClick).Resources(r => r .Set("ButtonBackground", Theme.SubtleFill) .Set("ButtonBackgroundPointerOver", Theme.Ref("SubtleFillColorSecondaryBrush")) .Set("ButtonBackgroundPressed", Theme.Ref("SubtleFillColorTertiaryBrush")) .Set("ButtonBorderBrush", Theme.SubtleFill) .Set("ButtonBorderBrushPointerOver", Theme.SubtleFill) .Set("ButtonBorderBrushPressed", Theme.SubtleFill)) // Wrong: setting Background directly — loses hover/pressed/disabled states Button("Action", onClick).Background(Theme.SubtleFill) ``` Resource keys target the `SolidColorBrush` resource (ending in `Brush`), not the `Color`. ```csharp // Correct .Set("ButtonBackground", Theme.Ref("ControlFillColorDefaultBrush")) // Wrong — Color, not Brush .Set("ButtonBackground", Theme.Ref("ControlFillColorDefault")) ``` ### 3. High Contrast Rules (Strict) High Contrast users rely on a fixed set of 8 system color brushes. Your UI must work with these constraints. **Allowed HC system brushes:** | Brush | Purpose | |-------|---------| | `SystemColorWindowTextColorBrush` | Text on window background | | `SystemColorWindowColorBrush` | Window/content background | | `SystemColorHighlightTextColorBrush` | Selected text foreground | | `SystemColorHighlightColorBrush` | Selection/hover background | | `SystemColorButtonTextColorBrush` | Button text | | `SystemColorButtonFaceColorBrush` | Button background | | `SystemColorGrayTextColorBrush` | Disabled/inactive text | | `SystemColorHotlightColorBrush` | Hyperlinks | **HC color pairings:** | Background | Foreground | Use Case | |------------|------------|----------| | `SystemColorWindowColor` | `SystemColorWindowTextColor` | General content | | `SystemColorHighlightColor` | `SystemColorHighlightTextColor` | Selected/hover states | | `SystemColorButtonFaceColor` | `SystemColorButtonTextColor` | Buttons | | `SystemColorWindowColor` | `SystemColorGrayTextColor` | Disabled content | | `SystemColorWindowColor` | `SystemColorHotlightColor` | Hyperlinks | **Rules:** - No hardcoded colors in HC mode. - No opacity on elements or brushes in HC — encode translucency in the alpha channel for Light/Dark only. - No accent colors or regular WinUI brushes in HC. - No gradient animations in HC — use a single system brush. - Use 2px border thickness for flyouts, dialogs, and cards in HC. - **No partial theme updates** — when changing Light/Dark visual resources via `.Resources()`, include matching HC-safe values in the same change. Don't leave HC untested. - **Interactive containers in HC need a highlight border** — for clickable cards or list items, add a `SystemColorHighlightColor` border in HC to indicate interactivity. - **Empty HC dictionary is valid** — when `.Resources()` overrides target only Light/Dark and WinUI defaults already satisfy accessibility, you don't need to add HC-specific overrides. - Set `HighContrastAdjustment` at app level to prevent system overrides: ```csharp Application.Current.HighContrastAdjustment = ApplicationHighContrastAdjustment.None; ``` Using `Theme.*` tokens correctly means HC usually "just works" because WinUI resolves them to appropriate system colors. Test to verify. ### 4. Typography Must Use Semantic Styles Use the predefined text factories or WinUI style tokens. Never set `FontSize` and `FontWeight` directly for standard UI text. **Reactor text factories:** | Factory | Size | Weight | Use Case | |---------|------|--------|----------| | `Caption("text")` | 12px | Regular | Small labels, timestamps | | `TextBlock("text")` | 14px | Regular | Default body text | | `Body("text")` | 14px | Regular | WinUI `BodyTextBlockStyle` body text | | `BodyStrong("text")` | 14px | Semibold | Emphasized inline labels | | `BodyLarge("text")` | 18px | Regular | Prominent body text | | `Subtitle("text")` | 20px | Semibold | WinUI `SubtitleTextBlockStyle` — section headings | | `SubHeading("text")` | 20px | 600 | Section headers, card titles (Reactor preset) | | `Title("text")` | 28px | Semibold | WinUI `TitleTextBlockStyle` — page titles | | `Heading("text")` | 28px | 700 | Page titles (Reactor preset, slightly heavier) | | `TitleLarge("text")` | 40px | Semibold | WinUI `TitleLargeTextBlockStyle` — primary titles on feature/landing pages | | `Display("text")` | 68px | Semibold | WinUI `DisplayTextBlockStyle` — hero banners, at most one per page | The `Title`/`Subtitle`/`Body`/`BodyStrong`/`BodyLarge`/`TitleLarge`/`Display` factories map 1:1 to WinUI's named TextBlock styles (Spec 039 §17.6). Prefer them when matching WinUI design specs; the `Heading`/`SubHeading` factories are the older Reactor presets and remain valid. **Font weight helpers:** | Helper | Weight | Use Case | |--------|--------|----------| | `.SemiBold()` | 600 | Emphasized body text, inline labels, field headers | | `.Bold()` | 700 | Reserved for `Heading()` page titles — avoid elsewhere | ```csharp TextBlock("Important label").SemiBold()