support to add theme v2

Author: RongqiZ

sharepoint/sharepoint-ps/Microsoft.Online.SharePoint.PowerShell/Add-SPOTheme.md

@@ -18,22 +18,37 @@ Creates a new custom theme, or overwrites an existing theme to modify its settin
 
 ## SYNTAX
 
+### LegacyThemeSet
 ```
-Add-SPOTheme [-Identity] <SpoThemePipeBind> -Palette <SpoThemePalettePipeBind> -IsInverted <Boolean>
- [-Overwrite] [<CommonParameters>]
+Add-SPOTheme
+    [-Identity] <SpoThemePipeBind>
+    -Palette <SpoThemePalettePipeBind>
+    -IsInverted <Boolean>
+    [-Overwrite]
+    [<CommonParameters>]
 ```
 
-## DESCRIPTION
+### NewThemeSet
+```
+Add-SPOTheme
+    [-Identity] <SpoThemePipeBind>
+    -ColorPairs <SpoThemeColorPairPipeBind>
+    [-Overwrite]
+    [<CommonParameters>]
+```
 
-The **Add-SPOTheme** cmdlet creates a new theme or updates an existing theme. The color palette settings can be passed as either a hash table or a dictionary.
+## DESCRIPTION
+The **Add-SPOTheme** cmdlet creates a new theme or updates an existing theme. The color palette and color pairs settings can be passed as either a hash table or a dictionary.
 
 Adding a theme does not apply the theme to any sites. It adds the theme to your tenant store, and then the theme is available in the list of themes under the **Change the look** option for modern pages.
 
-## EXAMPLES
+You can choose which parameter set to use depending on the legacy or new theme format you want to add. Please read [Site theme](https://learn.microsoft.com/sharepoint/site-theme) for more about new theme.
+
 
-### Example 1
+## Examples
 
-In this example, a new theme named `"Custom Cyan"` is created, with color palette settings that are various shades of cyan. Note that the settings are passed as a hash table.
+### Example 1: Add a legacy format theme 
+In this example, a theme named `"Custom Cyan"` is created, with color palette settings that are various shades of cyan. Note that the settings are passed as a hash table.
 
 ```powershell
 $themepalette = @{
@@ -70,14 +85,37 @@ Add-SPOTheme -Identity "Custom Cyan" -Palette $themepalette -IsInverted $false
 > [!NOTE]
 > Prior to the December 2017 release of the SPO Management Shell, the **Add-SPOTheme** cmdlet required that color palette settings be passed as a dictionary. We recommend that you use the latest version of the SPO Management Shell, or use the `HashToDictionary` function to convert a hash table to a dictionary if needed.
 
-### Example 2
+### Example 2: Overwrite a legacy format theme 
 
-If you want to update an existing theme (to modify some of its color settings, for example), use the same syntax as shown previously, but add the `-Overwrite` flag to the **Add-SPOTheme** cmdlet.
+If you want to update an existing legacy format theme (to modify some of its color settings, for example), use the same syntax as shown previously, but add the `-Overwrite` flag to the **Add-SPOTheme** cmdlet.
 
 ```powershell
 Add-SPOTheme -Identity "Custom Cyan" -Palette $themepalette -IsInverted $false -Overwrite
 ```
 
+### Example 3: Add a new format theme
+```powershell
+$colorPairs = @{
+    light = @(
+        @{
+            foregroundColor = '#00ffff'
+            backgroundColor = '#fff'
+        },
+        @{
+            foregroundColor = '#fff'
+            backgroundColor = '#00ffff'
+        }
+    )
+}
+
+Add-SPOTheme -Identity "Custom Cyan" -ColorPairs $colorPairs
+```
+
+### Example 4: Overwrite a new format theme
+```powershell
+Add-SPOTheme -Identity "Custom Cyan" -ColorPairs $colorPairs -Overwrite
+```
+
 ## PARAMETERS
 
 ### -Identity
@@ -98,36 +136,36 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -IsInverted
+### -Overwrite
 
 > Applicable: SharePoint Online
 
-Specifies whether the theme is inverted, with a dark background and a light foreground.
+Overwrites a theme of the same name in case it exists.
 
 ```yaml
-Type: System.Boolean
+Type: System.Management.Automation.SwitchParameter
 Parameter Sets: (All)
 Aliases: None
 
-Required: True
+Required: False
 Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Overwrite
+### -ColorPairs
 
 > Applicable: SharePoint Online
 
-Overwrites a theme of the same name in case it exists.
+Specifies the color pairs of the theme, as a dictionary or hash table of theme slot values. Supports up to 16 color pairs.
 
 ```yaml
-Type: System.Management.Automation.SwitchParameter
-Parameter Sets: (All)
-Aliases: None
+Type: Microsoft.Online.SharePoint.PowerShell.SpoThemeColorPairPipeBind
+Parameter Sets: NewThemeSet
+Aliases:
 
-Required: False
+Required: True
 Position: Named
 Default value: None
 Accept pipeline input: False
@@ -138,11 +176,11 @@ Accept wildcard characters: False
 
 > Applicable: SharePoint Online
 
-Specifies the palette of colors in the theme, as a dictionary of theme slot values.
+Specifies the palette of colors in the theme, as a dictionary or hash table of theme slot values.
 
 ```yaml
 Type: Microsoft.Online.SharePoint.PowerShell.SpoThemePalettePipeBind
-Parameter Sets: (All)
+Parameter Sets: LegacyThemeSet
 Aliases:
 
 Required: True
@@ -155,6 +193,24 @@ Accept wildcard characters: False
 ### CommonParameters
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
+### -IsInverted
+
+> Applicable: SharePoint Online
+
+Specifies whether the theme is inverted, with a dark background and a light foreground.
+
+```yaml
+Type: System.Boolean
+Parameter Sets: LegacyThemeSet
+Aliases: None
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ## INPUTS
 
 ### Microsoft.Online.SharePoint.PowerShell.SpoThemePipeBind