From a6d54a2a9972add074093f6365b772b26443a580 Mon Sep 17 00:00:00 2001 From: Miles Malerba Date: Thu, 26 Oct 2023 23:51:02 +0000 Subject: [PATCH] docs(material/theming): Fix broken theme guide formatting (#28015) Our docs site does not support the definition-list markdown, so I switched to headers instead. I also added a link from the generated schematic comment to the relevant documentation so users can learn more. (cherry picked from commit 58ecb1882848d43c62ac4f2a11928be921565a3c) --- guides/theming.md | 24 ++++++++++++------- .../migrations/theme-base-v17/migration.ts | 3 +++ .../ng-update/test-cases/theme-base.spec.ts | 21 ++++++++++++++++ 3 files changed, 39 insertions(+), 9 deletions(-) diff --git a/guides/theming.md b/guides/theming.md index 23b319405fe6..f6339ee2b5c2 100644 --- a/guides/theming.md +++ b/guides/theming.md @@ -241,37 +241,43 @@ your project's `angular.json` file][adding-styles]. #### Theming dimensions -Angular Material themes are divided along several dimensions: +Angular Material themes are divided along four dimensions: base, color, typography, and density. -Base -: Common base styles for the design system. These styles don't change based on your configured +##### Base + +Common base styles for the design system. These styles don't change based on your configured colors, typography, or density, so they only need to be included once per application. These mixins include structural styles such as border-radius, border-width, etc. All components have a base mixin that can be used to include its base styles. (For example, `@include mat.checkbox-base($theme)`) -Color -: Styles related to the colors in your application. These style should be included at least once in +##### Color + +Styles related to the colors in your application. These style should be included at least once in your application. Depending on your needs, you may need to include these styles multiple times with different configurations. (For example, if your app supports light and dark theme colors.) All components have a color mixin that can be used to include its color styles. (For example, `@include mat.checkbox-color($theme)`) -Typography -: Styles related to the fonts used in your application, including the font family, size, weight, +##### Typography + +Styles related to the fonts used in your application, including the font family, size, weight, line-height, and letter-spacing. These style should be included at least once in your application. Depending on your needs, you may need to include these styles multiple times with different configurations. (For example, if your app supports reading content in either a serif or sans-serif font.) All components have a typography mixin that can be used to include its typography styles. (For example, `@include mat.checkbox-typography($theme)`) -Density -: Styles related to the size and spacing of elements in your application. These style should be +##### Density + +Styles related to the size and spacing of elements in your application. These style should be included at least once in your application. Depending on your needs, you may need to include these styles multiple times with different configurations. (For example, if your app supports both a normal and compact mode). All components have a density mixin that can be used to include its density styles. (For example, `@include mat.checkbox-density($theme)`) +##### Theme mixin + All components also support a theme mixin that can be used to include the component's styles for all theme dimensions at once. (For example, `@include mat.checkbox-theme($theme)`). diff --git a/src/material/schematics/ng-update/migrations/theme-base-v17/migration.ts b/src/material/schematics/ng-update/migrations/theme-base-v17/migration.ts index 64b936ca1c34..406b096620df 100644 --- a/src/material/schematics/ng-update/migrations/theme-base-v17/migration.ts +++ b/src/material/schematics/ng-update/migrations/theme-base-v17/migration.ts @@ -17,6 +17,9 @@ const MISSING_MIXIN_PREAMBLE_LINES = ` // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // +// To learn more about "base" theme styles visit our theming guide: +// https://material.angular.io/guide/theming#theming-dimensions +// // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included.\ `.split('\n'); diff --git a/src/material/schematics/ng-update/test-cases/theme-base.spec.ts b/src/material/schematics/ng-update/test-cases/theme-base.spec.ts index a204e7cc23f6..ac0b47ea9e5a 100644 --- a/src/material/schematics/ng-update/test-cases/theme-base.spec.ts +++ b/src/material/schematics/ng-update/test-cases/theme-base.spec.ts @@ -56,6 +56,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.button-base(/* TODO(v17): pass $your-theme here */); @@ -91,6 +94,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include material.all-component-bases(/* TODO(v17): pass $your-theme here */); @@ -123,6 +129,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.card-base(/* TODO(v17): pass $your-theme here */); @@ -160,6 +169,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.all-component-bases(/* TODO(v17): pass $your-theme here */); @@ -225,6 +237,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.slider-base(/* TODO(v17): pass $your-theme here */); @@ -244,6 +259,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.slider-base(/* TODO(v17): pass $your-theme here */); @@ -296,6 +314,9 @@ describe('theme base mixins migration', () => { // Please note: you do not need to include the 'base' mixins, if you include the corresponding // 'theme' mixin elsewhere in your Sass. The full 'theme' mixins already include the base styles. // + // To learn more about "base" theme styles visit our theming guide: + // https://material.angular.io/guide/theming#theming-dimensions + // // TODO(v17): Please move these @include statements to the preferred place in your Sass, and pass // your theme to them. This will ensure the correct values for your app are included. @include mat.form-field-base(/* TODO(v17): pass $your-theme here */);