[Do not merge] Draft guidance doc for property pane custom control theme implementation

docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md

@@ -17,6 +17,12 @@ The source of the working web part is available on GitHub at [sp-dev-fx-webparts
 > [!NOTE]
 > Before following the steps in this article, be sure to [set up your development environment](../../set-up-your-development-environment.md) for building SharePoint Framework solutions.
 
+## Theming and Design Principles
+
+When building custom property pane controls, it is important to ensure they align with the broader SharePoint design language. For new controls, this includes following proper theming principles, which ensures controls follow the SharePoint property pane framework theme.
+
+For detailed guidance on implementing proper theming and using Fluent UI v9 design tokens in your custom controls, see [Property pane control theming implementation](./property-pane-theme-principles.md).
+
 
 ## Create new project
 
@@ -215,6 +221,9 @@ When creating a custom property pane control that uses React in the SharePoint F
 
 ### Add asynchronous dropdown property pane control React component
 
+> [!NOTE]
+> The example in this section uses Fluent UI v8 components. For new projects, we recommend using Fluent UI v9 components with design tokens. See [Property pane control theming implementation](./property-pane-theme-principles.md) for examples using Fluent UI v9.
+
 1. Create the components folder. In the project **src** folder, create a hierarchy of three new folders so that your folder structure appears as **src/controls/PropertyPaneAsyncDropdown/components**.
 
     ![Components folder highlighted in Visual Studio Code](../../../images/custom-property-pane-control-components-folder.png)

docs/spfx/web-parts/guidance/property-pane-theme-principles.md

@@ -0,0 +1,35 @@
+---
+title: "Property pane control theming implementation"
+description: "Learn how to implement property pane controls that follow SharePoint's theme framework and design principles."
+ms.date: 02/10/2026
+ms.localizationpriority: high
+---
+
+# Property pane control theming implementation
+
+To ensure a cohesive and consistent user experience across SharePoint sites, property pane custom controls should adhere to the **SharePoint Theme Framework**. This framework aims to rationalize theming for transient surfaces like property panes, drawers, and dialogs.
+
+## The Philosophy
+
+The core principle for **Property Pane controls** is simple: **they should not use the custom site theme**. Instead, these controls should always follow the **DOM tree property pane theme**, which is controlled internally by SharePoint.
+
+This approach ensures that property panes remain consistent with the overall application chrome regardless of the specific site's branding.
+
+## Technical Implementation Requirements
+
+Developers are strongly encouraged to use **Fluent UI v9** for all new custom controls. Fluent UI v9 can automatically detect and use the theme from the SharePoint property pane framework.
+
+> [!NOTE]
+> Both Fluent UI v8 components and legacy v8 color tokens will use the site theme instead of the property pane theme, which can cause visual misalignment with other property pane controls and may lead to accessibility issues.
+
+### Fluent UI v9 Components
+
+Fluent UI v9 components can automatically detect and use the theme from the SharePoint property pane framework, while Fluent UI v8 components cannot.
+
+You can explore the available components and their usage in the [Fluent UI v9 Components Storybook](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs). This resource provides interactive examples and documentation for all v9 controls.
+
+### Fluent UI v9 Design Tokens
+
+Hardcoded hex values for colors (e.g. `#0078d4`) should be avoided. Similarly, **Legacy v8 color tokens** (such as classes like `ms-color-neutralPrimary` or variables) should no longer be used, as they reflect the site theme and may cause accessibility issues. You should use Fluent UI v9 Design Tokens to handle theming logic. This ensures your control follows the theme from the SharePoint property pane framework.
+
+If you have existing controls using v8 color tokens, you should update them to the corresponding v9 tokens. You can find the legacy-to-v9 mapping here: [Fluent UI v8 to v9 Color Token Mapping](https://github.com/microsoft/fluentui/blob/2d6aca289ee6cc4571e4e3dcdf810deb78ac18fa/apps/public-docsite-v9/src/shims/ThemeShim/v9ThemeShim.ts#L14C1-L14C80).

docs/toc.yml

@@ -183,6 +183,8 @@
           href: spfx/web-parts/guidance/build-custom-property-pane-controls.md
         - name: Use cascading dropdowns
           href: spfx/web-parts/guidance/use-cascading-dropdowns-in-web-part-properties.md
+        - name: Property pane control theming implementation
+          href: spfx/web-parts/guidance/property-pane-theme-principles.md
     - name: Concepts & scenarios
       items:
       - name: Preconfigure web parts