diff --git a/docs/user-guide/theming.md b/docs/user-guide/theming.md index 87767b7b28..543760da6f 100644 --- a/docs/user-guide/theming.md +++ b/docs/user-guide/theming.md @@ -32,79 +32,30 @@ an [online palette design tool](http://mcg.mbitson.com/). See the [Material Design Style page](https://material.io/guidelines/style/color.html#) for more information about color concepts. -## Defining a custom theme +## Using Angular Material theming -When you want more customization than a pre-built theme offers, you can create your own theme file. You only need to include the packages you actually use in your application. +ADF is based on Angular Material library, which offers solutions for theming your application with either: +- Material Design 2 https://material.angular.dev/guide/material-2-theming +- Material Design 3 https://material.angular.dev/guide/theming -```scss -/* - * Include only packages that you are using (and core by default) - */ -@use '@angular/material' as mat; -@import '~@angular/material/theming'; -@import '~@alfresco/adf-core/theming'; +If you already setup Angular Material theming in the application you use ADF in, there is no need for taking additional steps to theme ADF components - colors, typography and other parts of the theme will be taken from your setup. -@include mat.core(); +## Customizing deprecated theme variables -$primary: mat.define-palette($alfresco-accent-orange); -$accent: mat.define-palette($alfresco-accent-purple); -$warn: mat.define-palette($alfresco-warn); -$theme: mat.define-light-theme(( - color: ( - primary: $primary, - accent: $accent, - warn: $warn, - ), - typography: $alfresco-typography -)); +Currently we have an amount of custom variables around components to mange libraries look and feel consistently and globally. -@include angular-material-theme($theme); -@include alfresco-material-theme($theme); -``` +While they are getting deprecated to be replaced with [Angular Material system variables](https://material.angular.dev/guide/system-variables), for seamless integration with Angular Material's theming, you can provide values for those variables inside the `:root` element. -### Multiple themes - -You can create multiple themes for your application: - -#### Example of defining multiple themes - -```scss -@import '~@angular/material/theming'; -@import '~@alfresco/adf-core/theming'; - -@include mat-core($alfresco-typography); - -$primary: mat.define-palette($alfresco-accent-orange); -$accent: mat.define-palette($alfresco-accent-purple); -$warn: mat.define-palette($alfresco-warn); -$theme: mat.define-light-theme(( - color: ( - primary: $primary, - accent: $accent, - warn: $warn, - ), - typography: $alfresco-typography -)); - -$dark-theme: mat.define-dark-theme(( - color: ( - primary: $primary, - accent: $accent, - warn: $warn, - ), - typography: $alfresco-typography -)); - -@include alfresco-material-theme($theme); -...like above - -.adf-dark-theme { - @include alfresco-material-theme($dark-theme); - ...like above +For example: +```css +:root { + --theme-primary-color: --mat-sys-primary; + --theme-accent-color: --mat-sys-tertiary; } ``` -Any component with the `add-dark-theme` class will use the dark theme, while other components will fall back to the default. +**No new variables should be added to the project** +[Reference list of overridable variables](https://github.com/Alfresco/alfresco-ng2-components/blob/29d341cc3b6a0842a776464027dcb1154875a8f0/lib/core/src/lib/styles/_index.scss#L25) ## Default reusable class @@ -132,13 +83,13 @@ Avoid adding css variables with custom values, values should come from the theme --new-variable: mat.get-color-from-palette($primary, 50), // good ``` -When styling components try to use theme related variables (colors, typography): -``` +When styling components use Angular Material system variables (colors, typography, elevation): +```scss .my-class { color:darkgrey; // bad - color:var(--theme-primary-color); // good + color:var(--mat-sys-primary); // good font-size:23px; // bad - font-size:var(--theme-typography-body-1-font-size); // good + font:var(--mat-sys-body-small); // good background:yellow; // bad background:var(--my-component-nr-200-background-color); // bad background:var(--theme-primary-color-50); // good @@ -148,7 +99,7 @@ When styling components try to use theme related variables (colors, typography): When using library like Angular Material try to follow patterns from this library. It helps to style components built with this library (just apply theme instead of custom styling). For example when creating input: -``` +```html // bad
@@ -166,3 +117,16 @@ For example when creating input: ``` + +Avoid customizing Angular Material's internal selectors: + +```scss +// bad - targeting internal Angular Material selectors +.mat-mdc-form-field .mdc-text-field__input { + color: red; +} + +.mat-mdc-button .mdc-button__label { + font-weight: bold; +} +``` diff --git a/lib/core/src/lib/styles/material.theme.scss b/lib/core/src/lib/styles/_globals.scss similarity index 98% rename from lib/core/src/lib/styles/material.theme.scss rename to lib/core/src/lib/styles/_globals.scss index 388c77882c..f8c1ea3119 100644 --- a/lib/core/src/lib/styles/material.theme.scss +++ b/lib/core/src/lib/styles/_globals.scss @@ -1,6 +1,6 @@ @use './mat-selectors' as ms; -@mixin adf-material-theme() { +@mixin globals() { #{ms.$mat-expansion-panel} { & #{ms.$mat-expansion-panel-header}.cdk-keyboard-focused, & #{ms.$mat-expansion-panel-header}.cdk-program-focused, diff --git a/lib/core/src/lib/styles/_index.scss b/lib/core/src/lib/styles/_index.scss index c56394767e..87e279c3ef 100644 --- a/lib/core/src/lib/styles/_index.scss +++ b/lib/core/src/lib/styles/_index.scss @@ -1,126 +1,4 @@ -/* stylelint-disable value-keyword-case */ -@use '@angular/material' as mat; -@use '@mat-datetimepicker/core/datetimepicker/datetimepicker-theme'; -/* stylelint-disable value-list-max-empty-lines */ -/* stylelint-disable scss/no-global-function-names */ -/* stylelint-disable scss/at-import-partial-extension */ -@import './mixins'; -@import './mat-selectors'; -@import '../form/components/widgets/form.theme'; -@import '../clipboard/clipboard.theme'; -@import './material.theme'; - -@mixin alfresco-material-theme($theme) { - @include adf-core-theme($theme); -} - -@mixin adf-core-theme($theme, $custom-css-variables: $adf-custom-theme-sizes) { - $foreground: map-get($theme, foreground); - $background: map-get($theme, background); - $warn: map-get($theme, warn); - $accent: map-get($theme, accent); - $primary: map-get($theme, primary); - $typography: map-get($theme, typography); - - // map SCSS variables to expose as CSS variables - $defaults: ( - // theme colors - --theme-primary-color: mat.m2-get-color-from-palette($primary), - --theme-primary-color-default-contrast: mat.m2-get-color-from-palette($primary, default-contrast), - --theme-header-text-color: mat.m2-get-color-from-palette($primary, default-contrast), - --adf-theme-primary-50: mat.m2-get-color-from-palette($primary, 50), - --adf-theme-primary-100: mat.m2-get-color-from-palette($primary, 100), - --adf-theme-primary-300: mat.m2-get-color-from-palette($primary, 300), - --adf-theme-primary-900: mat.m2-get-color-from-palette($primary, 900), - --theme-warn-color: mat.m2-get-color-from-palette($warn), - --theme-warn-color-a700: mat.m2-get-color-from-palette($warn, A700), - --theme-warn-color-default-contrast: mat.m2-get-color-from-palette($warn, default-contrast), - --theme-accent-color: mat.m2-get-color-from-palette($accent), - --theme-accent-color-a200: mat.m2-get-color-from-palette($accent, A200), - --theme-accent-color-default-contrast: mat.m2-get-color-from-palette($accent, default-contrast), - --theme-accent-500: mat.m2-get-color-from-palette($accent, 500), - --adf-theme-foreground-base-color: mat.m2-get-color-from-palette($foreground, base), - --adf-theme-foreground-base-color-065: mat.m2-get-color-from-palette($foreground, base, 0.65), - --adf-theme-foreground-base-color-045: mat.m2-get-color-from-palette($foreground, base, 0.45), - --adf-theme-foreground-disabled-text-color: mat.m2-get-color-from-palette($foreground, disabled-text), - --adf-theme-foreground-divider-color: mat.m2-get-color-from-palette($foreground, divider), - --adf-theme-foreground-icon-color: mat.m2-get-color-from-palette($foreground, icon), - --adf-theme-foreground-icon-color-054: mat.m2-get-color-from-palette($foreground, icon, 0.54), - --adf-theme-foreground-secondary-text-color: mat.m2-get-color-from-palette($foreground, secondary-text), - --adf-theme-foreground-text-color: mat.m2-get-color-from-palette($foreground, text), - --adf-theme-foreground-text-color-087: mat.m2-get-color-from-palette($foreground, text, 0.87), - --adf-theme-foreground-text-color-075: mat.m2-get-color-from-palette($foreground, text, 0.75), - --adf-theme-foreground-text-color-064: mat.m2-get-color-from-palette($foreground, text, 0.64), - --adf-theme-foreground-text-color-054: mat.m2-get-color-from-palette($foreground, text, 0.54), - --adf-theme-foreground-text-color-040: mat.m2-get-color-from-palette($foreground, text, 0.4), - --adf-theme-foreground-text-color-027: mat.m2-get-color-from-palette($foreground, text, 0.27), - --adf-theme-foreground-text-color-025: mat.m2-get-color-from-palette($foreground, text, 0.25), - --adf-theme-foreground-text-color-014: mat.m2-get-color-from-palette($foreground, text, 0.14), - --adf-theme-foreground-text-color-007: mat.m2-get-color-from-palette($foreground, text, 0.07), - --adf-theme-background-card-color: mat.m2-get-color-from-palette($background, card), - --adf-theme-background-card-color-087: mat.m2-get-color-from-palette($background, card, 0.87), - --theme-background-color: mat.m2-get-color-from-palette($background, background), - --adf-theme-background-dialog-color: mat.m2-get-color-from-palette($background, dialog), - --adf-theme-background-hover-color: mat.m2-get-color-from-palette($background, hover), - --adf-theme-background-selected-button-color: mat.m2-get-color-from-palette($background, selected-button), - --adf-theme-background-status-bar-color: mat.m2-get-color-from-palette($background, status-bar), - --adf-theme-background-unselected-chip-color: mat.m2-get-color-from-palette($background, unselected-chip), - // typography - --theme-font-family: mat.m2-font-family($typography), - --theme-font-weight: normal, - --theme-body-1-font-size: mat.m2-font-size($typography, body-2), - --theme-body-2-font-size: mat.m2-font-size($typography, subtitle-2), - --theme-body-1-line-height: mat.m2-line-height($typography, body-2), - --theme-display-1-font-size: mat.m2-font-size($typography, headline-4), - --theme-display-3-font-size: mat.m2-font-size($typography, headline-2), - --theme-display-4-font-size: mat.m2-font-size($typography, headline-1), - --theme-caption-font-size: mat.m2-font-size($typography, caption), - --theme-title-font-size: mat.m2-font-size($typography, headline-6), - --theme-subheading-1-font-size: mat.m2-font-size($typography, body-1), - --theme-subheading-2-font-size: mat.m2-font-size($typography, subtitle-1), - --theme-button-font-size: mat.m2-font-size($typography, button), - --theme-headline-font-size: mat.m2-font-size($typography, headline-5), - --theme-headline-line-height: mat.m2-line-height($typography, headline-5), - --theme-adf-icon-1-font-size: map-get($custom-css-variables, 'theme-adf-icon-1-font-size'), - --theme-adf-picture-1-font-size: map-get($custom-css-variables, 'theme-adf-picture-1-font-size'), - --theme-adf-task-footer-font-size: map-get($custom-css-variables, 'theme-adf-task-footer-font-size'), - --theme-adf-task-title-font-size: map-get($custom-css-variables, 'theme-adf-task-title-font-size'), - // specific colors - --adf-theme-mat-grey-color-a200: mat.m2-get-color-from-palette(mat.$m2-grey-palette, 'A200'), - --adf-theme-mat-grey-color-a400: mat.m2-get-color-from-palette(mat.$m2-grey-palette, 'A400'), - --adf-theme-mat-grey-color-50: mat.m2-get-color-from-palette(mat.$m2-grey-palette, 50), - // spacing - --adf-theme-spacing: map-get($custom-css-variables, 'theme-adf-spacing'), - // components - --adf-metadata-property-panel-border-color: rgba(0, 0, 0, 0.12), - --adf-metadata-buttons-background-color: rgba(33, 33, 33, 0.05), - --adf-metadata-action-button-clear-color: rgba(33, 35, 40, 0.698), - --adf-metadata-property-panel-text-color: rgba(33, 35, 40, 0.7), - --adf-metadata-property-panel-label-color: rgba(33, 33, 33, 0.24), - --adf-metadata-property-panel-title-color: rgb(33, 33, 33), - --adf-error-color: #ba1b1b, - --adf-secondary-button-background: #2121210d, - --adf-secondary-modal-text-color: #212121, - --adf-disabled-button-background: rgba(0, 0, 0, 0.12), - --adf-chip-border-color: #757575, - --adf-sidenav-active-text-color: rgba(0, 48, 100, 1) - ); - - // propagates SCSS variables into the CSS variables scope - :root { - @each $name, $value in $defaults { - #{$name}: #{$value}; - } - } - - @include datetimepicker-theme.mat-datetimepicker-theme($theme); - @include adf-material-theme; -} - -$adf-custom-theme-sizes: ( - 'theme-adf-icon-1-font-size': 17px, - 'theme-adf-picture-1-font-size': 18px, - 'theme-adf-task-footer-font-size': 18px, - 'theme-adf-task-title-font-size': 18px, - 'theme-adf-spacing': 16px -); +@forward './globals'; +@forward './flex'; +@forward './mixins'; +@forward './mat-selectors'; diff --git a/lib/core/src/lib/styles/_theming.scss b/lib/core/src/lib/styles/_theming.scss deleted file mode 100644 index 2e5834d7f8..0000000000 --- a/lib/core/src/lib/styles/_theming.scss +++ /dev/null @@ -1,3 +0,0 @@ -@import './mixins'; -@import './typography'; -@import './mat-selectors'; diff --git a/lib/core/src/lib/styles/_typography.scss b/lib/core/src/lib/styles/_typography.scss deleted file mode 100644 index 2006dab428..0000000000 --- a/lib/core/src/lib/styles/_typography.scss +++ /dev/null @@ -1,18 +0,0 @@ -@use '@angular/material' as mat; - -$alfresco-typography: mat.m2-define-typography-config( - $font-family: 'Roboto, "Helvetica Neue", sans-serif', - $headline-1: mat.m2-define-typography-level(112px, 112px, 300), - $headline-2: mat.m2-define-typography-level(56px, 56px, 400), - $headline-3: mat.m2-define-typography-level(45px, 48px, 400), - $headline-4: mat.m2-define-typography-level(34px, 40px, 400), - $headline-5: mat.m2-define-typography-level(24px, 32px, 400), - $headline-6: mat.m2-define-typography-level(20px, 32px, 500), - $subtitle-1: mat.m2-define-typography-level(16px, 28px, 400), - $body-1: mat.m2-define-typography-level(15px, 24px, 400), - $subtitle-2: mat.m2-define-typography-level(14px, 24px, 500), - $body-2: mat.m2-define-typography-level(14px, 20px, 400), - $caption: mat.m2-define-typography-level(12px, 20px, 400), - $button: mat.m2-define-typography-level(14px, 14px, 500), - // Line-height must be unit-less fraction of the font-size. -);