From d737d270eabb38de7211e8790ba8d841e060b1aa Mon Sep 17 00:00:00 2001 From: yidansun Date: Tue, 10 Feb 2026 18:36:07 +0800 Subject: [PATCH 1/4] Add draft doc --- .../build-custom-property-pane-controls.md | 6 + .../guidance/neutral-theme-principles.md | 158 ++++++++++++++++++ docs/toc.yml | 2 + 3 files changed, 166 insertions(+) create mode 100644 docs/spfx/web-parts/guidance/neutral-theme-principles.md diff --git a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md index 6d8359d65..feda4d967 100644 --- a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md +++ b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md @@ -14,6 +14,12 @@ In this article, you'll build a custom dropdown control that loads its data asyn The source of the working web part is available on GitHub at [sp-dev-fx-webparts/samples/react-custompropertypanecontrols/](https://github.com/SharePoint/sp-dev-fx-webparts/tree/master/samples/react-custompropertypanecontrols). +## 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 adhering to the **SharePoint Theme Framework**, which ensures controls integrate seamlessly with the property pane's internal styling. + +For detailed guidance on implementing proper theming and using Fluent UI v9 design tokens in your custom controls, see [SharePoint Theme Framework & Design Rules](./neutral-theme-principles.md). + > [!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. diff --git a/docs/spfx/web-parts/guidance/neutral-theme-principles.md b/docs/spfx/web-parts/guidance/neutral-theme-principles.md new file mode 100644 index 000000000..941fa781b --- /dev/null +++ b/docs/spfx/web-parts/guidance/neutral-theme-principles.md @@ -0,0 +1,158 @@ +--- +title: "Neutral Theme Framework & Design Rules for SharePoint" +description: "Learn about the Neutral Theme principles and how to implement them in your SharePoint Framework web parts." +ms.date: 02/10/2026 +ms.localizationpriority: high +--- + +# SharePoint Theme Framework & Design Rules + +To ensure a cohesive and consistent user experience across SharePoint sites, custom controls and web parts 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 must 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 with Fluent UI v9 + +Developers are strongly encouraged to use **Fluent UI v9** components for all new custom controls. If you are currently using Fluent UI v8 (formerly Office UI Fabric), consider migrating to v9 to take advantage of the latest design tokens and performance improvements. + +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. + +### Using Design Tokens + +Hardcoded hex values for colors (e.g. `#0078d4`) are **strictly forbidden**. Similarly, **Legacy v8 color tokens** (such as classes like `ms-color-neutralPrimary` or variables) should no longer be used. You must use Fluent UI v9 Design Tokens to handle theming logic. This ensures your control automatically adapts to the environment it is running in (Light/Dark mode, High Contrast, etc.). + +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). + +### Code Example: Custom Property Pane Control + +Here is an example of how to build a custom React component for the property pane using Fluent UI v9 and Design Tokens. + +**1. Install Dependencies** + +First, ensure you have the Fluent UI v9 packages installed: + +```console +npm install @fluentui/react-components @fluentui/react-icons +``` + +**2. Create the Component** + +This component uses `makeStyles` for styling and directly references the design tokens. + +```typescript +import * as React from 'react'; +import { + Dropdown, + Option, + Spinner, + makeStyles, + tokens, + SelectionEvents, + OptionOnSelectData +} from '@fluentui/react-components'; + +// Define props for the component +export interface IAsyncDropdownProps { + label: string; + loadOptions: () => Promise>; + onChanged: (option: { key: string | number; text: string }) => void; + selectedKey: string | number; + disabled: boolean; +} + +// Use makeStyles with Design Tokens for theming support +const useStyles = makeStyles({ + root: { + display: 'flex', + flexDirection: 'column', + gap: '5px', + backgroundColor: tokens.colorNeutralBackground1, // Use token for background + }, + label: { + paddingTop: '5px', + fontWeight: tokens.fontWeightSemibold, + color: tokens.colorNeutralForeground1, // Use token for text + }, + spinner: { + marginTop: '10px', + }, + error: { + color: tokens.colorPaletteRedForeground1, // Use token for error text + marginTop: '5px', + } +}); + +const AsyncDropdown: React.FC = (props) => { + const styles = useStyles(); + const [loading, setLoading] = React.useState(false); + const [options, setOptions] = React.useState>([]); + const [error, setError] = React.useState(undefined); + + React.useEffect(() => { + setLoading(true); + props.loadOptions() + .then((opts) => { + setLoading(false); + setOptions(opts); + }) + .catch((err) => { + setLoading(false); + setError(err.toString()); + }); + }, [props.disabled]); + + const onSelect = (event: SelectionEvents, data: OptionOnSelectData): void => { + const selectedOption = options.find(o => o.key.toString() === data.optionValue); + if (selectedOption) { + props.onChanged(selectedOption); + } + }; + + const selectedValue = props.selectedKey ? props.selectedKey.toString() : undefined; + const selectedText = options.find(o => o.key.toString() === selectedValue)?.text; + + return ( +
+ {props.label && } + + {options.map((option) => ( + + ))} + + + {loading && ( +
+ +
+ )} + + {error && ( +
+ Error: {error} +
+ )} +
+ ); +}; + +export default AsyncDropdown; +``` + +By following these standards, your custom controls will feel native to SharePoint and align with the internal property pane theming automatically. + +## References + +- [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) +- [Fluent UI v9 Components Storybook](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs) diff --git a/docs/toc.yml b/docs/toc.yml index b6e0e85ba..0e6df3e41 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -199,6 +199,8 @@ href: spfx/web-parts/basics/determine-web-part-width.md - name: Support section backgrounds href: spfx/web-parts/guidance/supporting-section-backgrounds.md + - name: SharePoint Theme Framework + href: spfx/web-parts/guidance/neutral-theme-principles.md - name: Web part top actions href: spfx/web-parts/guidance/getting-started-with-top-actions.md - name: Isolated web parts From 2123fadc6481ecc351d4721123918f6a3ff72ac1 Mon Sep 17 00:00:00 2001 From: yidansun Date: Wed, 11 Feb 2026 10:15:06 +0800 Subject: [PATCH 2/4] Polish and rename file --- .../build-custom-property-pane-controls.md | 7 +- .../guidance/neutral-theme-principles.md | 158 ----------------- .../guidance/propertypane-theme-principles.md | 162 ++++++++++++++++++ docs/toc.yml | 4 +- 4 files changed, 169 insertions(+), 162 deletions(-) delete mode 100644 docs/spfx/web-parts/guidance/neutral-theme-principles.md create mode 100644 docs/spfx/web-parts/guidance/propertypane-theme-principles.md diff --git a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md index feda4d967..4216bb354 100644 --- a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md +++ b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md @@ -16,9 +16,9 @@ The source of the working web part is available on GitHub at [sp-dev-fx-webparts ## 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 adhering to the **SharePoint Theme Framework**, which ensures controls integrate seamlessly with the property pane's internal styling. +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 integrate seamlessly with the property pane's internal styling. -For detailed guidance on implementing proper theming and using Fluent UI v9 design tokens in your custom controls, see [SharePoint Theme Framework & Design Rules](./neutral-theme-principles.md). +For detailed guidance on implementing proper theming and using Fluent UI v9 design tokens in your custom controls, see [Propertypane control theme and design rules](./propertypane-theme-principles.md). > [!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. @@ -221,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 [Propertypane control theme and design rules](./propertypane-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) diff --git a/docs/spfx/web-parts/guidance/neutral-theme-principles.md b/docs/spfx/web-parts/guidance/neutral-theme-principles.md deleted file mode 100644 index 941fa781b..000000000 --- a/docs/spfx/web-parts/guidance/neutral-theme-principles.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Neutral Theme Framework & Design Rules for SharePoint" -description: "Learn about the Neutral Theme principles and how to implement them in your SharePoint Framework web parts." -ms.date: 02/10/2026 -ms.localizationpriority: high ---- - -# SharePoint Theme Framework & Design Rules - -To ensure a cohesive and consistent user experience across SharePoint sites, custom controls and web parts 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 must 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 with Fluent UI v9 - -Developers are strongly encouraged to use **Fluent UI v9** components for all new custom controls. If you are currently using Fluent UI v8 (formerly Office UI Fabric), consider migrating to v9 to take advantage of the latest design tokens and performance improvements. - -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. - -### Using Design Tokens - -Hardcoded hex values for colors (e.g. `#0078d4`) are **strictly forbidden**. Similarly, **Legacy v8 color tokens** (such as classes like `ms-color-neutralPrimary` or variables) should no longer be used. You must use Fluent UI v9 Design Tokens to handle theming logic. This ensures your control automatically adapts to the environment it is running in (Light/Dark mode, High Contrast, etc.). - -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). - -### Code Example: Custom Property Pane Control - -Here is an example of how to build a custom React component for the property pane using Fluent UI v9 and Design Tokens. - -**1. Install Dependencies** - -First, ensure you have the Fluent UI v9 packages installed: - -```console -npm install @fluentui/react-components @fluentui/react-icons -``` - -**2. Create the Component** - -This component uses `makeStyles` for styling and directly references the design tokens. - -```typescript -import * as React from 'react'; -import { - Dropdown, - Option, - Spinner, - makeStyles, - tokens, - SelectionEvents, - OptionOnSelectData -} from '@fluentui/react-components'; - -// Define props for the component -export interface IAsyncDropdownProps { - label: string; - loadOptions: () => Promise>; - onChanged: (option: { key: string | number; text: string }) => void; - selectedKey: string | number; - disabled: boolean; -} - -// Use makeStyles with Design Tokens for theming support -const useStyles = makeStyles({ - root: { - display: 'flex', - flexDirection: 'column', - gap: '5px', - backgroundColor: tokens.colorNeutralBackground1, // Use token for background - }, - label: { - paddingTop: '5px', - fontWeight: tokens.fontWeightSemibold, - color: tokens.colorNeutralForeground1, // Use token for text - }, - spinner: { - marginTop: '10px', - }, - error: { - color: tokens.colorPaletteRedForeground1, // Use token for error text - marginTop: '5px', - } -}); - -const AsyncDropdown: React.FC = (props) => { - const styles = useStyles(); - const [loading, setLoading] = React.useState(false); - const [options, setOptions] = React.useState>([]); - const [error, setError] = React.useState(undefined); - - React.useEffect(() => { - setLoading(true); - props.loadOptions() - .then((opts) => { - setLoading(false); - setOptions(opts); - }) - .catch((err) => { - setLoading(false); - setError(err.toString()); - }); - }, [props.disabled]); - - const onSelect = (event: SelectionEvents, data: OptionOnSelectData): void => { - const selectedOption = options.find(o => o.key.toString() === data.optionValue); - if (selectedOption) { - props.onChanged(selectedOption); - } - }; - - const selectedValue = props.selectedKey ? props.selectedKey.toString() : undefined; - const selectedText = options.find(o => o.key.toString() === selectedValue)?.text; - - return ( -
- {props.label && } - - {options.map((option) => ( - - ))} - - - {loading && ( -
- -
- )} - - {error && ( -
- Error: {error} -
- )} -
- ); -}; - -export default AsyncDropdown; -``` - -By following these standards, your custom controls will feel native to SharePoint and align with the internal property pane theming automatically. - -## References - -- [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) -- [Fluent UI v9 Components Storybook](https://storybooks.fluentui.dev/react/?path=/docs/concepts-introduction--docs) diff --git a/docs/spfx/web-parts/guidance/propertypane-theme-principles.md b/docs/spfx/web-parts/guidance/propertypane-theme-principles.md new file mode 100644 index 000000000..222e1d32c --- /dev/null +++ b/docs/spfx/web-parts/guidance/propertypane-theme-principles.md @@ -0,0 +1,162 @@ +--- +title: "Propertypane control theme and design rules" +description: "Learn about the propertypane control theme principles and how to implement them in your SharePoint Framework web parts." +ms.date: 02/10/2026 +ms.localizationpriority: high +--- + +# Propertypane control theme and design rules + +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 with Fluent UI v9 + +Developers are strongly encouraged to use **Fluent UI v9** components for all new custom controls. Fluent UI v9 components can automatically detect and use the theme from the SharePoint property pane framework, while Fluent UI v8 components rely on React context and cannot access the property pane theme. If you are currently using Fluent UI v8 (formerly Office UI Fabric), consider migrating to v9. Controls built with v8 will use the site theme instead, which can cause visual misalignment with other property pane controls and may lead to accessibility issues. + +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. + +### Using 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. 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). + +### Code Example: Custom Property Pane Control + +Here is an example of how to build a custom asynchronous dropdown React component for the property pane using Fluent UI v9 and Design Tokens. This example is based on the pattern from [Build custom controls for the property pane](./build-custom-property-pane-controls.md), updated to use Fluent UI v9. + +**1. Install Dependencies** + +First, ensure you have the Fluent UI v9 packages installed: + +```console +npm install @fluentui/react-components +``` + +**2. Create the Component** + +This component uses `makeStyles` for styling and directly references the design tokens. + +```typescript +import * as React from 'react'; +import { + Dropdown, + Option, + Spinner, + makeStyles, + tokens, + SelectionEvents, + OptionOnSelectData +} from '@fluentui/react-components'; +import { IDropdownOption } from '@fluentui/react/lib/Dropdown'; + +export interface IAsyncDropdownProps { + label: string; + loadOptions: () => Promise; + onChanged: (option: IDropdownOption, index?: number) => void; + selectedKey: string | number; + disabled: boolean; + stateKey: string; +} + +export interface IAsyncDropdownState { + loading: boolean; + options: IDropdownOption[] | undefined; + error: string | undefined; +} + +// Use makeStyles with Design Tokens for theming support +const useStyles = makeStyles({ + label: { + fontWeight: tokens.fontWeightSemibold, + color: tokens.colorNeutralForeground1, + }, + error: { + color: tokens.colorPaletteRedForeground1, + } +}); + +const AsyncDropdown: React.FC = (props) => { + const styles = useStyles(); + const [state, setState] = React.useState({ + loading: false, + options: undefined, + error: undefined + }); + + const loadOptions = React.useCallback(() => { + setState({ + loading: true, + error: undefined, + options: undefined + }); + + props.loadOptions() + .then((options: IDropdownOption[]) => { + setState({ + loading: false, + error: undefined, + options: options + }); + }) + .catch((error: any) => { + setState({ + loading: false, + error: error.toString(), + options: undefined + }); + }); + }, [props.loadOptions]); + + React.useEffect(() => { + loadOptions(); + }, [props.disabled, props.stateKey, loadOptions]); + + const onOptionSelect = (event: SelectionEvents, data: OptionOnSelectData): void => { + const selectedOption = state.options?.find(o => o.key.toString() === data.optionValue); + if (selectedOption) { + props.onChanged(selectedOption, state.options?.indexOf(selectedOption)); + } + }; + + const selectedValue = props.selectedKey?.toString(); + const selectedText = state.options?.find(o => o.key.toString() === selectedValue)?.text; + + return ( +
+ {props.label && } + + {state.options?.map((option) => ( + + ))} + + + {state.loading && } + + {state.error && ( +
+ Error while loading items: {state.error} +
+ )} +
+ ); +}; + +export default AsyncDropdown; +``` + +This example shows how to use Fluent UI v9 components with design tokens. The component automatically follows the SharePoint property pane framework theme. diff --git a/docs/toc.yml b/docs/toc.yml index 0e6df3e41..48bbbc3cf 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -199,8 +199,8 @@ href: spfx/web-parts/basics/determine-web-part-width.md - name: Support section backgrounds href: spfx/web-parts/guidance/supporting-section-backgrounds.md - - name: SharePoint Theme Framework - href: spfx/web-parts/guidance/neutral-theme-principles.md + - name: Propertypane control theme and design rules + href: spfx/web-parts/guidance/propertypane-theme-principles.md - name: Web part top actions href: spfx/web-parts/guidance/getting-started-with-top-actions.md - name: Isolated web parts From c8902a7610a4a650ef783635d941ae389f0dc1cd Mon Sep 17 00:00:00 2001 From: yidansun Date: Wed, 11 Feb 2026 15:15:12 +0800 Subject: [PATCH 3/4] Polish description and rename file --- .../build-custom-property-pane-controls.md | 6 +- .../property-pane-theme-principles.md | 35 ++++ .../guidance/propertypane-theme-principles.md | 162 ------------------ docs/toc.yml | 4 +- 4 files changed, 40 insertions(+), 167 deletions(-) create mode 100644 docs/spfx/web-parts/guidance/property-pane-theme-principles.md delete mode 100644 docs/spfx/web-parts/guidance/propertypane-theme-principles.md diff --git a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md index 4216bb354..b364c3be0 100644 --- a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md +++ b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md @@ -14,15 +14,15 @@ In this article, you'll build a custom dropdown control that loads its data asyn The source of the working web part is available on GitHub at [sp-dev-fx-webparts/samples/react-custompropertypanecontrols/](https://github.com/SharePoint/sp-dev-fx-webparts/tree/master/samples/react-custompropertypanecontrols). +> [!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 integrate seamlessly with the property pane's internal styling. For detailed guidance on implementing proper theming and using Fluent UI v9 design tokens in your custom controls, see [Propertypane control theme and design rules](./propertypane-theme-principles.md). -> [!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. - ## Create new project diff --git a/docs/spfx/web-parts/guidance/property-pane-theme-principles.md b/docs/spfx/web-parts/guidance/property-pane-theme-principles.md new file mode 100644 index 000000000..f74212fc7 --- /dev/null +++ b/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). diff --git a/docs/spfx/web-parts/guidance/propertypane-theme-principles.md b/docs/spfx/web-parts/guidance/propertypane-theme-principles.md deleted file mode 100644 index 222e1d32c..000000000 --- a/docs/spfx/web-parts/guidance/propertypane-theme-principles.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: "Propertypane control theme and design rules" -description: "Learn about the propertypane control theme principles and how to implement them in your SharePoint Framework web parts." -ms.date: 02/10/2026 -ms.localizationpriority: high ---- - -# Propertypane control theme and design rules - -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 with Fluent UI v9 - -Developers are strongly encouraged to use **Fluent UI v9** components for all new custom controls. Fluent UI v9 components can automatically detect and use the theme from the SharePoint property pane framework, while Fluent UI v8 components rely on React context and cannot access the property pane theme. If you are currently using Fluent UI v8 (formerly Office UI Fabric), consider migrating to v9. Controls built with v8 will use the site theme instead, which can cause visual misalignment with other property pane controls and may lead to accessibility issues. - -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. - -### Using 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. 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). - -### Code Example: Custom Property Pane Control - -Here is an example of how to build a custom asynchronous dropdown React component for the property pane using Fluent UI v9 and Design Tokens. This example is based on the pattern from [Build custom controls for the property pane](./build-custom-property-pane-controls.md), updated to use Fluent UI v9. - -**1. Install Dependencies** - -First, ensure you have the Fluent UI v9 packages installed: - -```console -npm install @fluentui/react-components -``` - -**2. Create the Component** - -This component uses `makeStyles` for styling and directly references the design tokens. - -```typescript -import * as React from 'react'; -import { - Dropdown, - Option, - Spinner, - makeStyles, - tokens, - SelectionEvents, - OptionOnSelectData -} from '@fluentui/react-components'; -import { IDropdownOption } from '@fluentui/react/lib/Dropdown'; - -export interface IAsyncDropdownProps { - label: string; - loadOptions: () => Promise; - onChanged: (option: IDropdownOption, index?: number) => void; - selectedKey: string | number; - disabled: boolean; - stateKey: string; -} - -export interface IAsyncDropdownState { - loading: boolean; - options: IDropdownOption[] | undefined; - error: string | undefined; -} - -// Use makeStyles with Design Tokens for theming support -const useStyles = makeStyles({ - label: { - fontWeight: tokens.fontWeightSemibold, - color: tokens.colorNeutralForeground1, - }, - error: { - color: tokens.colorPaletteRedForeground1, - } -}); - -const AsyncDropdown: React.FC = (props) => { - const styles = useStyles(); - const [state, setState] = React.useState({ - loading: false, - options: undefined, - error: undefined - }); - - const loadOptions = React.useCallback(() => { - setState({ - loading: true, - error: undefined, - options: undefined - }); - - props.loadOptions() - .then((options: IDropdownOption[]) => { - setState({ - loading: false, - error: undefined, - options: options - }); - }) - .catch((error: any) => { - setState({ - loading: false, - error: error.toString(), - options: undefined - }); - }); - }, [props.loadOptions]); - - React.useEffect(() => { - loadOptions(); - }, [props.disabled, props.stateKey, loadOptions]); - - const onOptionSelect = (event: SelectionEvents, data: OptionOnSelectData): void => { - const selectedOption = state.options?.find(o => o.key.toString() === data.optionValue); - if (selectedOption) { - props.onChanged(selectedOption, state.options?.indexOf(selectedOption)); - } - }; - - const selectedValue = props.selectedKey?.toString(); - const selectedText = state.options?.find(o => o.key.toString() === selectedValue)?.text; - - return ( -
- {props.label && } - - {state.options?.map((option) => ( - - ))} - - - {state.loading && } - - {state.error && ( -
- Error while loading items: {state.error} -
- )} -
- ); -}; - -export default AsyncDropdown; -``` - -This example shows how to use Fluent UI v9 components with design tokens. The component automatically follows the SharePoint property pane framework theme. diff --git a/docs/toc.yml b/docs/toc.yml index 48bbbc3cf..c84fff4b8 100644 --- a/docs/toc.yml +++ b/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 @@ -199,8 +201,6 @@ href: spfx/web-parts/basics/determine-web-part-width.md - name: Support section backgrounds href: spfx/web-parts/guidance/supporting-section-backgrounds.md - - name: Propertypane control theme and design rules - href: spfx/web-parts/guidance/propertypane-theme-principles.md - name: Web part top actions href: spfx/web-parts/guidance/getting-started-with-top-actions.md - name: Isolated web parts From a5010c61967d2c6af49bbefc5aecf4d7e236c641 Mon Sep 17 00:00:00 2001 From: yidansun Date: Wed, 11 Feb 2026 15:40:16 +0800 Subject: [PATCH 4/4] fix file path --- .../guidance/build-custom-property-pane-controls.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md index b364c3be0..e3c96c0db 100644 --- a/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md +++ b/docs/spfx/web-parts/guidance/build-custom-property-pane-controls.md @@ -19,9 +19,9 @@ The source of the working web part is available on GitHub at [sp-dev-fx-webparts ## 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 integrate seamlessly with the property pane's internal styling. +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 [Propertypane control theme and design rules](./propertypane-theme-principles.md). +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 @@ -222,7 +222,7 @@ 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 [Propertypane control theme and design rules](./propertypane-theme-principles.md) for examples using Fluent UI v9. +> 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**.