diff --git a/build/.markdownlint.json b/build/.markdownlint.json index 9731b6ade..372eaa4eb 100644 --- a/build/.markdownlint.json +++ b/build/.markdownlint.json @@ -4,5 +4,6 @@ "commands-show-output": false, "no-bare-urls": false, "no-inline-html": false, - "no-duplicate-heading": false + "no-duplicate-heading": false, + "MD051": false } \ No newline at end of file diff --git a/doc/assets/material-wizard.png b/doc/assets/material-wizard.png new file mode 100644 index 000000000..55a6fb828 Binary files /dev/null and b/doc/assets/material-wizard.png differ diff --git a/doc/cupertino-getting-started.md b/doc/cupertino-getting-started.md index ab1233105..e3764ce30 100644 --- a/doc/cupertino-getting-started.md +++ b/doc/cupertino-getting-started.md @@ -2,7 +2,7 @@ uid: Uno.Themes.Cupertino.GetStarted --- -# Uno.Cupertino +# Uno Cupertino

Cupertino design system @@ -13,33 +13,61 @@ Uno Cupertino is an add-on package that lets you apply [Cupertino - Human Interf ## Getting Started > [!NOTE] -> As of [Uno Platform 4.7](https://platform.uno/blog/uno-platform-4-7-new-project-template-performance-improvements-and-more/), the solution template of an Uno app has changed. There is no longer a Shared project (.shproj), it has been replaced with a regular cross-platform library containing all user code files, referred to as the **App Code Library** project. This also implies that package references can be included in a single location without the previous need to include those in all project heads. +> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022). -### Creating a new project with Uno.Cupertino installed from command-line +### Creating a new project with Uno Cupertino -1. Install `dotnet new` templates with: +1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with: - ```dotnetcli + ```bash dotnet new install Uno.Templates ``` 2. Create a new application with: - ```dotnetcli - dotnet new unoapp -o AppName -theme cupertino + ```bash + dotnet new unoapp -o UnoCupertinoApp -theme cupertino ``` -### Installing Uno.Cupertino in existing project that uses class library +### Installing Uno Cupertino in an existing project + +Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install Uno Cupertino. + +#### [**Single Project Template**](#tab/singleproj) + +1. Edit your project file (`PROJECT_NAME.csproj`) and add `Cupertino` to the list of `UnoFeatures`: + + ```xml + Cupertino + ``` + +2. Initialize the Cupertino resources in the `App.xaml`: + + ```xml + + + + + + + + + + + + + ``` + +#### [**Multi-Head Project Template (Legacy)**](#tab/multihead) 1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...` 1. Install the [`Uno.Cupertino.WinUI`](https://www.nuget.org/packages/Uno.Cupertino.WinUI) -1. Add the following Cupertino resources `AppResources.xaml`: +1. Add the following Cupertino resources to `AppResources.xaml`: ```xml - @@ -48,25 +76,22 @@ Uno Cupertino is an add-on package that lets you apply [Cupertino - Human Interf ``` -### Installing Uno.Cupertino on previous versions of Uno Platform - -If your application is based on the older solution template that includes a shared project (.shproj), follow these steps: +#### [**Shared Project (.shproj) Template (Legacy)**](#tab/shproj) -1. Open an existing Uno project -2. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either: +1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either: - The [`Uno.Cupertino`](https://www.nuget.org/packages/Uno.Cupertino/) package when targetting Xamarin/UWP - The [`Uno.Cupertino.WinUI`](https://www.nuget.org/packages/Uno.Cupertino.WinUI) package when targetting net6.0+/WinUI -3. Select the following projects for installation: +2. Select the following projects for installation: - `PROJECT_NAME.Wasm.csproj` - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project) - `PROJECT_NAME.Skia.Gtk.csproj` - `PROJECT_NAME.Skia.WPF.csproj` - `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects) -4. Add the following resources inside `App.xaml`: +3. Add the following resources inside `App.xaml`: ```xml - + @@ -88,13 +113,16 @@ If your application is based on the older solution template that includes a shar ``` +--- + ## Customization +The following guides require the creation of new `ResourceDictionary` files in your application project. For more information on how to define styles and resources in a separate `ResourceDictionary`, refer to the [resource management documentation](xref:Guide.HowTo.Create-Control-Library#moving-the-control-style-in-a-separate-resource-dictionary). + ### Customize Color Palette -1. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `CupertinoColorsOverride.xaml` -2. Save the new override file within the **App Code Library**, for example, under `Style/Application`. -3. Replace the content with: +1. Add a new Resource Dictionary named `CupertinoColorsOverride.xaml` to the application project, for example, under `Styles/Application`. +2. Replace the content with: ```xml ``` -4. In `AppResources.xaml`, update `` with the override from the previous steps: +3. In `App.xaml`, update `` with the override from the previous steps: ```xml + OverrideSource="ms-appx:///Styles/Application/CupertinoColorsOverride.xaml" /> ``` ### Change Default Font -By default, Uno.Cupertino comes pre-packaged with the [SF Pro](https://developer.apple.com/fonts/) `FontFamily` and automatically includes them in your application. Upon installation of the Uno.Cupertino package, you will have a `CupertinoFontFamily` resource available. +By default, Uno Cupertino comes pre-packaged with the [SF Pro](https://developer.apple.com/fonts/) `FontFamily` and automatically includes them in your application. Upon installation of the Uno Cupertino package, you will have a `CupertinoFontFamily` resource available. -If you would like Uno.Cupertino to use a different font, you can override the default `FontFamily` following these steps: +If you would like Uno Cupertino to use a different font, you can override the default `FontFamily` by following these steps: 1. Add the custom font following [Custom Fonts documentation](https://platform.uno/docs/articles/features/custom-fonts.html). -2. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `CupertinoFontsOverride.xaml`. -3. Save the new override file within the **App Code Library**, for example, under `Style/Application`. -4. Assuming the font file has been placed in the **App Code Library** within, for example, a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following: +2. Add a new Resource Dictionary named `CupertinoFontsOverride.xaml` to the application project, for example, under `Styles/Application`. +3. Assuming the font file has been placed in a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following: ```xml - ms-appx:///PROJECT_NAME/Assets/Fonts/MyCustomFont.ttf + ms-appx:///Assets/Fonts/MyCustomFont.ttf ``` -5. In `AppResources.xaml`, update `` with the override from the previous steps: +4. In the `App.xaml`, update `` with the override from the previous steps: ```xml + OverrideSource="ms-appx:///Styles/Application/CupertinoFontsOverride.xaml" /> ``` diff --git a/doc/fluent-getting-started.md b/doc/fluent-getting-started.md index efbc05d4b..894ce218f 100644 --- a/doc/fluent-getting-started.md +++ b/doc/fluent-getting-started.md @@ -23,7 +23,7 @@ The step-by-step process to enable Fluent design styles within an existing Uno P 1. In only the `UWP` head project of your solution, if you have one, install the [WinUI 2 NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml). This step is the same as required for WinUI 2 UWP apps. -1. Within the shared project used by all platform heads, add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`. This step is the same as required for WinUI 2 UWP apps. +1. Add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`. This step is the same as required for WinUI 2 UWP apps. ```xml @@ -48,5 +48,3 @@ The step-by-step process to enable Fluent design styles within an existing Uno P ``` - -1. In all platform head projects except UWP, the Fluent control styles require the Uno Fluent Assets icon font to display correctly. Follow [Uno Fluent UI assets documentation](https://platform.uno/docs/articles/uno-fluent-assets.html) to upgrade your app to use this font. This step is required because the Uno Platform uses a cross-platform ready default font within its styles different from UWP's *Segoe MDL2 Assets*. diff --git a/doc/material-getting-started.md b/doc/material-getting-started.md index ec1a7b03c..7e3e9b237 100644 --- a/doc/material-getting-started.md +++ b/doc/material-getting-started.md @@ -2,21 +2,21 @@ uid: Uno.Themes.Material.GetStarted --- -# Uno.Material +# Uno Material

Material design system

-The Uno.Material library is available as NuGet packages that can be added to any new or existing Uno solution. +The Uno Material library is available as NuGet packages that can be added to any new or existing Uno Platform solution. Uno Material lets you apply [Material Design 3](https://m3.material.io/) styling to your application with just a few lines of code. > [!WARNING] -> If you are updating Uno.Material to v2 from an older 1.x version of the package, additional steps will be required. Refer to the [Uno Material Migration Guide](material-migration.md). +> If you are updating Uno Material to v2 from an older 1.x version of the package, additional steps will be required. Refer to the [Uno Material Migration Guide](material-migration.md). ## Getting Started -Initialization of the Uno.Material resources is handled by the specialized `MaterialTheme` ResourceDictionary. +Initialization of the Uno Material resources is handled by the specialized `MaterialTheme` ResourceDictionary. ### `MaterialTheme` @@ -31,59 +31,94 @@ Initialization of the Uno.Material resources is handled by the specialized `Mate | Property | Type | Description | |-----------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `ColorOverrideSource` | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a `ResourceDictionary` containing overrides for the default Uno.Material Color resources | -| `FontOverrideSource` | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a `ResourceDictionary` containing overrides for the default Uno.Material font resources | +| `ColorOverrideSource` | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a `ResourceDictionary` containing overrides for the default Uno Material Color resources | +| `FontOverrideSource` | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a `ResourceDictionary` containing overrides for the default Uno Material font resources | -> [!NOTE] -> As of [Uno Platform 4.7](https://platform.uno/blog/uno-platform-4-7-new-project-template-performance-improvements-and-more/), the solution template of an Uno app has changed. There is no longer a Shared project (.shproj), it has been replaced with a regular cross-platform library containing all user code files, referred to as the **App Code Library** project. This also implies that package references can be included in a single location without the previous need to include those in all project heads. +### Creating a new project with Uno Material -### Creating a new project with Uno.Material installed from command-line +> [!NOTE] +> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022). -1. Install `dotnet new` templates with: +#### [**Wizard**](#tab/wizard) - ```dotnetcli +1. Follow the steps in the [Getting Started with Visual Studio](xref:Uno.GettingStarted.CreateAnApp.VS2022#create-the-app) instructions to launch the Uno Platform Template Wizard. +2. Select `Material` under the `Theme` section. + + ![Material selection in Wizard](assets/material-wizard.png) + +#### [**CLI**](#tab/cli) + +1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with: + + ```bash dotnet new install Uno.Templates ``` 2. Create a new application with: - ```dotnetcli - dotnet new unoapp -o AppName -theme material + ```bash + dotnet new unoapp -o UnoMaterialApp -theme material + ``` + +--- + +### Installing Uno Material in an existing project + +Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install Uno Material. + +#### [**Single Project Template**](#tab/singleproj) + +1. Edit your project file (`PROJECT_NAME.csproj`) and add `Material` to the list of `UnoFeatures`: + + ```xml + Material + ``` + +2. Initialize `MaterialTheme` in the `App.xaml`: + + ```xml + + + + + + + + + + ``` -### Installing Uno.Material in existing project that uses class library +#### [**Multi-Head Project Template (Legacy)**](#tab/multihead) 1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...` -1. Install the [`Uno.Material.WinUI`](https://www.nuget.org/packages/Uno.Material.WinUI) -1. Add the following Material resources to `AppResources.xaml`: +2. Install the [`Uno.Material.WinUI`](https://www.nuget.org/packages/Uno.Material.WinUI) +3. Add the following Material resources to `AppResources.xaml`: ```xml - + ``` -### Installing Uno.Material on previous versions of Uno Platform - -If your application is based on the older solution template that includes a shared project (.shproj), follow these steps: +#### [**Shared Project (.shproj) Template (Legacy)**](#tab/shproj) -1. Open an existing Uno project -2. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either: +1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either: - The [`Uno.Material`](https://www.nuget.org/packages/Uno.Material/) package when targetting Xamarin/UWP - The [`Uno.Material.WinUI`](https://www.nuget.org/packages/Uno.Material.WinUI) package when targetting net6.0+/WinUI -3. Select the following projects for installation: +2. Select the following projects for installation: - `PROJECT_NAME.Wasm.csproj` - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project) - `PROJECT_NAME.Skia.Gtk.csproj` - `PROJECT_NAME.Skia.WPF.csproj` - `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects) -4. Add the following resources inside `App.xaml`: +3. Add the following resources inside `App.xaml`: ```xml @@ -94,7 +129,7 @@ If your application is based on the older solution template that includes a shar - + @@ -106,25 +141,28 @@ If your application is based on the older solution template that includes a shar ``` +--- + ## Customization +The following guides require the creation of new `ResourceDictionary` files in your application project. For more information on how to define styles and resources in a separate `ResourceDictionary`, refer to the [resource management documentation](xref:Guide.HowTo.Create-Control-Library#moving-the-control-style-in-a-separate-resource-dictionary). + ### Color Overrides using _Material Theme Builder_ and DSP format -It is possible to use the [Material Theme Builder](https://m3.material.io/theme-builder#/custom) to generate a custom color palette derived from your own basic colors. The generated palette is provided in the [DSP format](https://m3.material.io/styles/color/the-color-system/color-dsp) and can be used to override the default Uno.Material colors. +It is possible to use the [Material Theme Builder](https://m3.material.io/theme-builder#/custom) to generate a custom color palette derived from your own basic colors. The generated palette is provided in the [DSP format](https://m3.material.io/styles/color/the-color-system/color-dsp) and can be used to override the default Uno Material colors. -The tooling required to generate the _Material Colors Override_ file from a DSP package (zip file) will be present by default when creating a _Uno Extensions_ project with support for Uno.Material. +The tooling required to generate the _Material Colors Override_ file from a DSP package (zip file) will be present by default when creating an Uno Platform application with support for Uno Material from the Wizard. ![Wizard - Theme Selection](assets/material-theme-selection-wizard.png) -Follow this link to get [more Information about the DSP tooling](xref:Uno.Material.DSP). +Follow this link to get [more Information about the DSP tooling](xref:Uno.Themes.Material.DSP). ### Manual Color Overrides -Use this when you want to specify MANUALLY each colors. +Use this when you want to manually override the default color palette from the Uno Material library. -1. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `MaterialColorsOverride.xaml` -2. Save the new override file within the **App Code Library**, for example, under `Styles/Application`. -3. Replace the content with: +1. Add a new Resource Dictionary named `MaterialColorsOverride.xaml` to the application project, for example, under `Styles/Application`. +2. Replace the content with: ```xml ``` -4. In `AppResources.xaml`, update `` with the override from the previous steps: +3. In `App.xaml`, update `` with the override from the previous steps: ```xml + ColorOverrideSource="ms-appx:///Styles/Application/MaterialColorsOverride.xaml" /> ``` ### Change Default Font -By default, Uno.Material comes pre-packaged with the [Roboto](https://fonts.google.com/specimen/Roboto) font families and automatically includes them in your application. Upon installation of the Uno.Material package, you will have the following resources available: `MaterialLightFontFamily`, `MaterialRegularFontFamily`, and `MaterialMediumFontFamily`. +By default, Uno Material comes pre-packaged with the [Roboto](https://fonts.google.com/specimen/Roboto) font families and automatically includes them in your application. Upon installation of the Uno Material package, you will have the following resources available: `MaterialLightFontFamily`, `MaterialRegularFontFamily`, and `MaterialMediumFontFamily`. -If you would like Uno.Material to use a different font, you can override the default font families following these steps: +If you would like Uno Material to use a different font, you can override the default font families by following these steps: 1. Add the custom font following [Custom Fonts documentation](https://platform.uno/docs/articles/features/custom-fonts.html). -2. In the application's **App Code Library** project (`PROJECT_NAME.csproj`), add a new Resource Dictionary named `MaterialFontsOverride.xaml`. -3. Save the new override file within the **App Code Library**, for example, under `Styles/Application`. -4. Assuming the font file has been placed in the **App Code Library** within, for example, a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following: +2. Add a new Resource Dictionary named `MaterialFontsOverride.xaml` to the application project, for example, under `Styles/Application`. +3. Assuming the font file has been placed in a directory such as `Assets/Fonts/MyCustomFont.ttf`, your override file would look like the following: ```xml - ms-appx:///PROJECT_NAME/Assets/Fonts/MyCustomFont-Light.ttf#MyCustomFont - ms-appx:///PROJECT_NAME/Assets/Fonts/MyCustomFont-Medium.ttf#MyCustomFont - ms-appx:///PROJECT_NAME/Assets/Fonts/MyCustomFont-Regular.ttfMyCustomFont + ms-appx:///Assets/Fonts/MyCustomFont.ttf#MyCustomFont + ms-appx:///Assets/Fonts/MyCustomFont.ttf#MyCustomFont + ms-appx:///Assets/Fonts/MyCustomFont.ttfMyCustomFont ``` -5. In `AppResources.xaml`, update `` with the override from the previous steps: +4. In the `App.xaml`, update `` with the override from the previous steps: ```xml + FontOverrideSource="ms-appx:///Styles/Application/MaterialFontsOverride.xaml" /> ``` ## Using C# Markup Uno Material also has support for C# Markup through a [Uno.Material.WinUI.Markup](https://www.nuget.org/packages/Uno.Material.WinUI.Markup) NuGet Package. -To get started with Uno Material in your C# Markup application, add the `Uno.Material.WinUI.Markup` NuGet package to your **App Code Library** project and your platform heads. -Then, add the following code to your `AppResources.cs`: +To get started with Uno Material in your C# Markup application, add the `Uno.Material.WinUI.Markup` NuGet package to your application project. + +Then, add the following code to your `App.xaml.cs`: ```csharp using Uno.Material.Markup; diff --git a/doc/themes-overview.md b/doc/themes-overview.md index 6b2e2660d..5b6e09c2d 100644 --- a/doc/themes-overview.md +++ b/doc/themes-overview.md @@ -16,16 +16,17 @@ uid: Uno.Themes.Overview ## Uno Themes Styles -[Uno.Themes](https://github.com/unoplatform/Uno.Themes) is the repository for add-ons NuGet packages that can be added to any new or existing Uno solution. +[Uno Themes](https://github.com/unoplatform/Uno.Themes) is the repository for add-ons NuGet packages that can be added to any new or existing Uno solution. -It contains two libraries: +It contains three libraries: -- `Uno.Material` library is designed to help you use [Material Design 3](https://m3.material.io/) -- `Uno.Cupertino` library is designed to help you use [Human Interface Guideline styling](https://developer.apple.com/design/human-interface-guidelines) +- `Uno Themes`: a library that contains the base resources, extensions, and helper classes for the different design system libraries +- `Uno Material`: a library that contains styles following the [Material 3](https://m3.material.io/) Design System +- `Uno Cupertino`: a library that contains styles following the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines) -Both libraries help you style your application with a few lines of code including: +Both `Material` and `Cupertino` libraries help you style your application with a few lines of code including: -- Color system for both Light and Dark theme +- Color system for both Light and Dark themes - Styles for existing WinUI controls like Buttons, TextBox, etc. ## Fluent Controls Styles