docs: Document Themes 7.0 / Toolkit 9.0 upgrade in the 6.6 migration notes

[agneszitte]

GitHub Issue: related to https://github.com/unoplatform/private/issues/1102

PR Type:

📚 Documentation content changes

What changed? 🚀

The 6.6 migration notes covered the core and Uno.Extensions changes from the initial 6.6 release, but not the design system packages moving up a major version in the service release: the SDK's implicit pins go from Uno.Themes 6.1.1 → 7.0.3 and Uno.Toolkit 8.4.2 → 9.0.3.

This adds a short "Uno Themes 7.0 and Uno Toolkit 9.0" entry under Uno Platform 6.6, matching the length and style of the other breaking-change entries in the file — one paragraph plus a bullet list of what breaks and what to do, with links out to the per-library upgrade guides:

• Deprecated MaterialToolkitResourcesV1/V2 dictionaries now fail at startup → use <MaterialToolkitTheme />.
• Generated dictionary URIs dropped the WinUI suffix (affects URI-based merges).
• MaterialToolkitTheme derives from MaterialTheme → don't declare <MaterialTheme /> alongside it.
• ColorOverrideSource/ColorOverrideDictionary obsolete → the Colors property: ThemeColors.OverrideSource for a file override, ThemeColors.OverrideDictionary for an inline ResourceDictionary.
• BaseTheme.GenerateSpecificResources() removed → the parameterless AddThemeSpecificResources() hook, with dictionaries added through AddThemeDictionary().
• Material v1 CommandBar and ToggleSwitch lost their iOS/Android variants.
• UWP-flavored Toolkit packages stop at 8.4.2; net9.0-maccatalyst / net9.0-macos assets dropped.
• Raised dependency floors and the Toolkit 9.0 ⇄ Themes 7.0 coupling.

It states up front that apps using the template pattern (<MaterialToolkitTheme />) need no changes, so a major version bump inside a service release doesn't read as more disruptive than it is.

Validation

Verified against the shipped packages rather than commit messages:

• Diffed the XAML resource-key sets and public API surfaces of Uno.Material.WinUI 6.1.1 → 7.0.3 and Uno.Toolkit.WinUI 8.4.2 → 9.0.3, plus nuspec dependency groups. No resource keys were removed from the shipped WinUI dictionaries other than NativeCommandBarTemplate — the other missing keys live in a NavigationView/WUX/** folder the WinUI package excludes, so they never shipped.
• Confirmed the Material Design 3 styles switched to design token resources (ButtonMinHeight → ControlHeightMedium, ButtonPadding → Space400HorizontalThickness, …) and traced BaseTheme.ScaleGeneration.cs to verify the token defaults equal the literals they replaced (40, 16, 20, …) at the default density and corner radius — hence "default appearance unchanged".
• Checked the lib/ assets of all 11 Themes and Toolkit packages: net9.0-maccatalyst and net9.0-macos present at 6.1.1/8.4.2, absent at 7.0.3/9.0.3. Last stable UWP-flavored Toolkit release is 8.4.2.
• Compared BaseTheme.UpdateSource() at both versions to confirm color override precedence is unchanged for apps that don't opt into seed colors.
• Built and ran a template-generated app (recommended preset, net10.0-desktop) on both stacks — baseline (6.1.1 / 8.4.2) and upgraded (7.0.3 / 9.0.3): both build with 0 warnings / 0 errors and launch cleanly.
• Reproduced the legacy-dictionary failure in that same app by swapping <MaterialToolkitTheme /> for <MaterialToolkitResourcesV2 />: runs on 8.4.2, crashes on 9.0.3 with Cannot locate resource from 'ms-appx:///Uno.Toolkit.WinUI.Material/Generated/mergedpages.WinUI.v2.xaml'.
• cspell --config ./build/cSpell.json passes on the edited file, and the previous push was green on Uno.UI - docs and Check Docs links, so both xref links resolve in a real docs build.

Following the automated review round, two points were folded in and one was declined on the evidence:

• The AddThemeSpecificResources signature is now given in the doc. Note it is parameterless (BaseTheme.cs:468 at tag 7.0.3) and implementers layer resources via the protected void AddThemeDictionary(ResourceDictionary) helper — the reviewer-suggested AddThemeSpecificResources(ResourceDictionary dictionary) overload does not exist.
• The inline-dictionary migration path was missing; ThemeColors.OverrideDictionary is confirmed against the shipped API and is now covered alongside OverrideSource.
• Windows App SDK 1.7 and the new SkiaSharp.Views dependency are intentionally not listed as floors a reader must act on: Uno.Sdk 6.6.33 already pins Microsoft.WindowsAppSDK to 1.7.250909003 (the exact floor Toolkit 9.0.3 declares) and SkiaSharp.Views.Uno.WinUI/.WinUI are already implicit SDK packages at 3.119.2, above the new 3.119.1 floor.

PR Checklist ✅

• 🧪 Added Runtime tests, UI tests, or a manual test sample (for bug fixes / features, if applicable) — N/A, documentation-only
• 📚 Docs have been added/updated following the documentation template (for bug fixes / features)
• 🖼️ Validated PR Screenshots Compare Test Run results — N/A, documentation-only
• ❗ Contains NO breaking changes
• 👀 Reviewed 2 other open pull requests (optional but appreciated!)

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

test seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[github-actions]

Claude finished @agneszitte's task in 3m 11s —— View job

---

PR Review

• Gather context and read changed files
• Review documentation content for accuracy and clarity
• Check xref links and formatting
• Post inline comments for findings
• Post review summary

---

Summary

This is a well-written, accurate documentation addition. Content is organized logically — impact-first (legacy dictionaries break at startup), then progressively less-common migration cases — and the "no changes needed for template apps" callout up front is valuable for reducing upgrade alarm.

Findings: 1 minor

Severity	Count
Minor	1

The one inline finding is on line 111: the AddThemeSpecificResources hook is mentioned as the replacement for GenerateSpecificResources(), but the new API signature is never shown. Custom theme authors are left with no in-context guidance on what to write. A stub method signature or a targeted link anchor into the external migration guide would resolve this.

Everything else looks good:

• Conventional Commits format followed (docs: type) ✓
• xref: links use correct cross-reference syntax ✓
• URI before/after table is clear and accurate ✓
• XAML and diff code blocks are well-formed ✓
• The ThemeColors.OverrideSource XML example is correct ✓
• Mac Catalyst fallback TFM explanation is technically accurate ✓
• cspell passing per PR description ✓

[Copilot]

Pull request overview

Updates the Uno Platform 6.6 migration notes to document the implicit design-system package upgrades that land in the 6.6 service release line (Uno.Themes 7.x and Uno.Toolkit 9.x), focusing on the real breaking/migration points app developers may hit.

Changes:

• Adds a new “Uno Themes 7.0 and Uno Toolkit 9.0” section under Uno Platform 6.6 migration notes.
• Documents key upgrade impacts (legacy dictionary startup failure, URI changes, theme initialization changes, obsolete color override APIs, custom theme hook changes, platform/package support shifts, and dependency floors).
• Links to the per-library migration guides via xref.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Claude finished @agneszitte's task in 2m 41s —— View job

---

PR Review

• Gather context and read changed files
• Review documentation content for accuracy and clarity
• Check xref links, formatting, and code blocks
• Post inline comments for findings
• Post review summary

---

Summary

The documentation is well-structured and accurate. The ordering — startup-breaking change first, then progressively less common migration paths — is the right call, and the "no changes needed for template apps" callout up front is genuinely useful.

Findings: 2 minor

Severity	Count
Minor	2

Both inline findings are on missing migration examples rather than inaccurate content:

1. Line 111 — AddThemeSpecificResources hook referenced but not defined; custom theme authors have no in-context guidance on the new method signature.
2. Line 96 — ColorOverrideDictionary (inline dictionary) migration path not shown; only the OverrideSource (URI) variant is demonstrated.

Other observations (no inline comment needed):

• The section intro at line 11 ("Uno Platform 6.6 contains a breaking change related to the removal of legacy Windows Phone namespaces") now undersells the scope of the 6.6 section since this PR adds eight more migration points. Updating that sentence to "contains breaking changes" or broadening it to acknowledge the design-system bump would improve accuracy. That sentence is pre-existing and not part of this diff, so it's not a blocker.
• xref:Toolkit.Migration and xref:Uno.Themes.Material.Migration are defined in the external repositories (uno.toolkit.ui, uno.themes) imported via import_external_docs.ps1. They cannot be resolved locally; worth validating in a deployed docs preview or against the external repo uid: declarations before merging if the /docs-build skill hasn't already been run.

Everything else looks good: diff code blocks render correctly, XAML namespace prefixes are consistent with Uno conventions, the URI before/after table is accurate, cspell passing per PR description, and Conventional Commits format is followed.

[github-actions]

Claude finished @agneszitte's task in 2m 26s —— View job

---

PR Review

• Gather context and read changed files
• Review documentation content for accuracy and clarity
• Check xref links and formatting
• Post inline comments for findings
• Post review summary

---

Summary

Well-structured documentation addition. The impact-first ordering (startup-breaking legacy dictionaries first, then progressively less common migration paths) is the right call, and the "no changes needed for template apps" callout up front will significantly reduce upgrade alarm for the majority of users.

Findings: 3 minor

Severity	Count
Minor	3

Inline findings:

1. Line 57 — AddThemeSpecificResources hook named as the replacement for GenerateSpecificResources() but the method signature is not shown. Custom theme authors are left with no in-context example of what to implement. A signature stub (or a pointed link to the anchor in the external guide) would unblock them.
2. Line 56 — ColorOverrideSource and ColorOverrideDictionary are both called out as obsolete, but only the OverrideSource (file URI) migration path is demonstrated. Users who had an inline ResourceDictionary via ColorOverrideDictionary have no equivalent shown.
3. Line 60 — PR description states Windows App SDK 1.7 and a new SkiaSharp.Views transitive dependency were verified as additional floors; neither appears in the docs. If these are hard NuGet constraints (rather than automatically-resolved transitives), apps with explicit pins could encounter unexpected resolution failures without this information.

Everything else looks good:

• xref: cross-reference syntax is correct for both external library guides ✓
• Conventional Commits format followed (docs: type, imperative mood) ✓
• XAML inline code blocks are well-formed ✓
• The "WinUI suffix dropped" URI change is accurate and clearly scoped ✓
• MaterialToolkitTheme double-init warning is technically accurate ✓
• Mac Catalyst / UWP package sunset is correctly scoped ✓

[github-actions]

Claude finished @agneszitte's task in 1m 45s —— View job

---

PR Review

• Gather context and read changed files
• Review documentation content for accuracy and clarity
• Check xref links, formatting, and code blocks
• Post inline comments for findings
• Post review summary

---

Summary

Well-structured, impact-first documentation addition. The "no changes needed for template apps" callout up front is genuinely useful for reducing upgrade alarm, and the ordering (startup-breaking case first, progressively less common paths after) is correct.

Findings: 2 minor

Severity	Count
Minor	2

Both inline findings are about missing migration detail, not inaccurate content:

1. Line 57 — AddThemeSpecificResources named as the GenerateSpecificResources() replacement but no method signature shown; custom theme authors are left without enough context to act without reading the library source.
2. Line 56 — ColorOverrideDictionary (inline dictionary) migration path not shown; only the OverrideSource (URI) variant is demonstrated; the inline-dictionary user has no equivalent example.

Other observations (no inline comment):

• The section intro at line 11 ("Uno Platform 6.6 contains a breaking change…") now undersells the scope of the 6.6 section given this PR adds eight more migration points — updating that to "contains breaking changes" would improve accuracy. That line is pre-existing and not part of this diff, so it is not a blocker.
• xref:Toolkit.Migration and xref:Uno.Themes.Material.Migration resolve from the externally-imported uno.toolkit.ui / uno.themes repos via import_external_docs.ps1. They cannot be validated locally; a deployed docs preview (or a check of the uid: declarations in those repos) before merge would confirm they resolve correctly.

Everything else looks good: Conventional Commits format followed (docs: type, imperative mood) ✓ · XAML inline code blocks well-formed ✓ · URI before/after change accurately described ✓ · MaterialToolkitTheme double-init warning technically accurate ✓ · Mac Catalyst / UWP package sunset correctly scoped ✓ · cspell passing per PR description ✓

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-23925/docs/index.html

[github-actions]

Claude finished @agneszitte's task in 1m 43s —— View job

---

PR Review

• Gather context and read changed files
• Review documentation content for accuracy and clarity
• Check for any remaining gaps after author responses
• Post inline comments for findings
• Post review summary

---

Summary

The documentation is accurate and well-structured. The author has correctly addressed all findings from previous review rounds:

• AddThemeSpecificResources() is now documented as parameterless (correcting the review's wrong suggested signature), with AddThemeDictionary() as the helper — verified against BaseTheme.cs:468 at tag 7.0.3. ✓
• ColorOverrideDictionary inline-dictionary migration path is now covered alongside the file-URI path. ✓
• Dependency floors (Uno.WinUI 6.5 / 6.4, Toolkit→Themes coupling) documented. ✓

No new findings.

Two non-blocking observations (no inline comment needed):

1. Line 11 (pre-existing, out of diff) — "Uno Platform 6.6 contains a breaking change" now undersells the section after this PR adds eight more migration points. Worth updating to "contains breaking changes" in a follow-up, but not a blocker.
2. xref links — xref:Toolkit.Migration and xref:Uno.Themes.Material.Migration resolve from the externally-imported uno.toolkit.ui / uno.themes repos. The staging site at https://unodocsprstaging.z13.web.core.windows.net/pr-23925/docs/index.html should be checked to confirm both links render correctly before merge.

[agneszitte]

@kazo0 the migration details after your review should move in the general xref:Toolkit.Migration and maybe best to have a more general xref:Uno.Themes.Migration instead of xref:Uno.Themes.Material.Migration

Let me know your thoughts please

[kazo0]

Yes indeed they should :)

These all look good!

[unodevops]

🤖 Your Docs stage site is ready! Visit it here: https://unodocsprstaging.z13.web.core.windows.net/pr-23925/docs/index.html