feat(theming): Full Skins & Themes Implementation (#369)

.squad/agents/beast/history.md

@@ -1009,3 +1009,50 @@ This wave establishes **documentation patterns** that will guide future control
 - Periodically auditing docs/ vs mkdocs.yml nav prevents doc fragmentation
 - Test artifacts (migration benchmark runs) should be excluded from main nav to reduce clutter  only index the summary report, not intermediate outputs
 
+---
+
+## Issue WI-6: Wave 1 Theming Documentation
+
+**Status:** DELIVERED
+
+**Session (2026 by Beast):**
+
+**Task:** Create comprehensive Wave 1 Theming Documentation for the Skins & Themes feature
+
+**Deliverables:**
+1. New file: `docs/themes-and-skins.md` (15,924 characters, 470 lines)
+   - 9 major sections covering all theming aspects
+   - 40+ code examples (C# ThemeConfiguration and Blazor HTML)
+   - Comprehensive comparison tables and API reference
+
+2. Navigation update: `mkdocs.yml`
+   - Added `- Themes and Skins: themes-and-skins.md` to main nav (line 67)
+   - Positioned after "Component Health Dashboard" for discoverability
+
+**Section Breakdown:**
+- **Overview** — Key concepts (ThemeConfiguration, ThemeProvider, ControlSkin, SkinID, ThemeMode)
+- **Quick Start** — 3-step minimal example (Define → Apply → Result)
+- **Theme Modes** — StyleSheetTheme vs Theme with comparison table and precedence rules
+- **Sub-Component Styles** — SubStyle API for GridView/DetailsView/FormView/DataGrid/DataList with counts
+- **Migration Guide** — Side-by-side Web Forms .skin files vs Blazor ThemeConfiguration
+- **EnableTheming & SkinID** — Opt-out patterns and named skin variants
+- **Runtime Theme Switching** — Dynamic theme switching example
+- **API Reference** — Complete tables for all types and properties
+- **Best Practices** — 6 key recommendations for theme development
+- **Troubleshooting** — Q&A for common theming issues
+
+**Verification:**
+- Markdown formatting verified (no syntax errors, proper tables, code blocks)
+- All 9 sections properly structured with --- dividers
+- Code examples complete and runnable
+- Cross-references to existing docs (Migration/ThemesAndSkins.md, StylingComponents.md, GridView.md)
+- mkdocs.yml navigation entry confirmed
+
+**Learnings:**
+- Theming documentation must bridge both Web Forms migration (pain point: .skin file conversion) AND Blazor-native usage (ThemeConfiguration builder pattern)
+- Comparison tables (StyleSheetTheme vs Theme) are essential for explaining precedence rules; developers need to understand WHY to choose one mode over another
+- Named skins (SkinID) are powerful for multi-variant theming  semantic names like "Danger", "Success" help developers implement button hierarchies quickly
+- Sub-component styling is critical for data controls  listing exact counts (GridView: 8, DetailsView: 10, etc.) helps developers discover available styling options
+- Positioning Themes & Skins near the top of nav (after dashboard) signals to developers that theming is a primary feature, not an advanced utility
+- Runtime theme switching example shows interactivity patterns that Blazor enables over static Web Forms themes
+

.squad/agents/bishop/history.md

@@ -0,0 +1,73 @@
+# Bishop - Migration Tooling Dev History
+
+## Role
+Bishop is the Migration Tooling Dev on the BlazorWebFormsComponents project, responsible for building migration tools and utilities that help developers move from ASP.NET Web Forms to Blazor.
+
+## Project Context
+BlazorWebFormsComponents is a library providing Blazor components that emulate ASP.NET Web Forms controls, enabling migration with minimal markup changes. The project aims to preserve the same component names, attributes, and HTML output as the original Web Forms controls.
+
+## Learnings
+
+### WI-8: .skin File Parser Implementation (2025-01-26)
+
+**Task**: Build a runtime parser that reads ASP.NET Web Forms .skin files and converts them into ThemeConfiguration objects.
+
+**Implementation Details**:
+- Created `SkinFileParser.cs` with three public methods:
+  - `ParseSkinFile(string, ThemeConfiguration)` - parses .skin content from string
+  - `ParseSkinFileFromPath(string, ThemeConfiguration)` - parses single .skin file from disk
+  - `ParseThemeFolder(string, ThemeConfiguration)` - parses all .skin files in a directory
+
+- Parsing approach:
+  - Strip ASP.NET comments (`<%-- ... --%>`)
+  - Wrap content in root element and replace `<asp:` with `<asp_` for XML compatibility
+  - Parse as XML using XDocument
+  - Walk element tree to build ControlSkin and TableItemStyle objects
+
+- Type conversions:
+  - WebColor: use `WebColor.FromHtml(value)` for color attributes
+  - Unit: use `new Unit(value)` for size/width attributes
+  - FontUnit: use `FontUnit.Parse(value)` for font sizes
+  - BorderStyle: use `Enum.TryParse<BorderStyle>()` for enum values
+  - Font attributes: special handling for `Font-Bold`, `Font-Italic`, `Font-Size`, etc.
+
+- Sub-styles: Nested elements like `<HeaderStyle>`, `<RowStyle>` become entries in `ControlSkin.SubStyles` dictionary as `TableItemStyle` objects
+
+- Error handling: Defensive parsing with try-catch blocks and console warnings, never throws on parse errors
+
+**Key Technical Decisions**:
+1. Used XML parsing after preprocessing rather than custom parser - leverages proven XML infrastructure
+2. Case-insensitive attribute and control name matching for robustness
+3. Silently ignore unknown attributes to handle variations in .skin files
+4. Console.WriteLine for warnings rather than throwing exceptions - allows partial parsing success
+
+**Build Status**: ✅ Successfully builds with no errors
+
+**Verification**: ✅ Tested with sample .skin content:
+- Successfully parsed default Button skin with colors and font properties
+- Successfully parsed named Button skin (SkinID="DangerButton")
+- Successfully parsed GridView with nested HeaderStyle and RowStyle sub-components
+- All color conversions, font attributes, and sub-styles worked correctly
+
+### Web Forms Theme Migration SKILL.md (2025-01-27)
+
+**Task**: Write a SKILL.md that teaches Copilot and Squad agents how to migrate Web Forms themes to Blazor using BWFC auto-discovery.
+
+**Delivered**:
+- Created `.squad/skills/theme-migration/SKILL.md` as authoritative reference for theme migration pattern
+- Documented Web Forms theme structure (App_Themes/ folder with .skin, .css, images)
+- Explained auto-discovery flow: copy → `AddBlazorWebFormsComponents()` → `SkinFileParser` → `ThemeProvider` injection
+- Covered key concepts:
+  - Theme folder identification and copy operation (preserve structure)
+  - Default theme selection (first folder alphabetically)
+  - CSS auto-discovery and injection via ThemeProvider
+  - Named skins (SkinID parameter requirement in Blazor)
+  - ThemeMode (StyleSheetTheme default vs. Theme override mode)
+  - Multiple themes support and custom ThemesPath configuration
+- Provided 3 detailed examples (simple, multiple themes, named skins)
+- Documented edge cases (no themes, CSS-only themes, custom paths)
+- Included anti-patterns with do's and don'ts (manual registration, missing ThemeProvider, image handling)
+
+**Why This Matters**: This SKILL.md replaces the need for agent-specific migration scripts. Any agent (Copilot, Cyclops, Rogue, or future Squad members) doing Web Forms migration now has a standardized reference explaining the theme pattern. No more tribal knowledge — the pattern is documented, discoverable, and reusable across projects.
+
+**Key Principle**: The SKILL teaches the "what" and "why" but delegates implementation details (SkinFileParser internals, ThemeProvider rendering) to library code. This keeps the SKILL maintainable as the implementation evolves.

.squad/agents/colossus/history.md

@@ -234,3 +234,19 @@ Added 5 smoke tests (Timer, UpdatePanel, UpdateProgress, ScriptManager, Substitu
 - `samples/AfterBlazorServerSide.Tests/ControlSampleTests.cs` — 3 new `[InlineData]` entries
 - `samples/AfterBlazorServerSide.Tests/InteractiveComponentTests.cs` — 11 new `[Fact]` methods
 
+### Theming Sections 7 & 8 Integration Tests (2026-03-22)
+
+**Summary:** Added 2 Playwright interaction tests for upcoming Theming page enhancements (Sections 7 & 8 being built by Jubilee).
+
+**Tests added to `InteractiveComponentTests.cs`:**
+1. `Theming_ThemeMode_StyleSheetThemeVsTheme` — Navigates to /ControlSamples/Theming, verifies Section 7 (ThemeMode) has an h3 heading matching "ThemeMode" or "Theme Mode", confirms both StyleSheetTheme and Theme panels are rendered with text content assertions, and checks at least 2 buttons exist across both panels.
+2. `Theming_SubStyles_GridViewHeaderAndFooter` — Navigates to /ControlSamples/Theming, verifies Section 8 (sub-styles/data controls) has an h3 heading, confirms a `<table>` (GridView) is present in that section, and asserts the table has `<th>` header cells.
+
+**Patterns:**
+- Used `HasTextRegex` with case-insensitive regex for heading matching — resilient to "ThemeMode" vs "Theme Mode" naming.
+- Used `.Filter(new() { Has = heading })` to scope assertions to the correct `.demo-container` section.
+- Used `?? string.Empty` on `TextContentAsync()` to eliminate CS8602 null reference warning.
+- Tests are written defensively to work once Jubilee adds Sections 7 & 8 — they will fail with clear messages until those sections land.
+
+**Coverage:** 1 smoke test (existing) + 1 existing interaction test + 2 new interaction tests = 4 total Theming tests.
+