Skip to content

Commit 42e24d1

Browse files
kdinevkdinev
authored
Merge pull request #6771 from IgniteUI/sivanova/theming-docs-9.0.x
Sivanova/theming docs 9.0.x
2 parents ac4ff56 + ba84ab7 commit 42e24d1

File tree

2 files changed

+23
-106
lines changed

2 files changed

+23
-106
lines changed

‎projects/igniteui-angular/src/lib/core/styles/README.md‎

Lines changed: 22 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,44 @@
11
## Ignite UI for Angular Themes
22

3-
Ignite UI for Angular includes a comprehensive set of **<a href="http://sass-lang.com/" target="_blank">Sass</a>** functions and mixins, giving you the power to easily style your entire application or only certain parts of it.
4-
5-
### The Essence of a Theme
6-
7-
Since **IgniteUI for Angular** bases its component designs on the **<a href="https://material.io/guidelines/material-design/introduction.html" target="_blank">Material Design Guidelines</a>**, we try to get as close as possible to colors, sizes, and overall look and feel of our components to those created by Google.
3+
### Overview
4+
Since **IgniteUI for Angular** bases its component designs on the **<a href="https://material.io/guidelines/material-design/introduction.html" target="_blank">Material Design Principles</a>**, we try to get as close as possible to colors, sizes, typography, and overall look and feel of our components to those created by Google.
85

96
Our approach to theming is based around several simple concepts.
107

11-
#### Palettes
12-
13-
The first concept is the one of palettes of colors. As in any visual tool, colors are the main differentiator between one application and another. The Material Design Guidelines prescribe predefined palettes of colors that range in hue and lightness for a base color. There's a good reason for that. They really want to ensure good color matching and contrast between the background colors and the foreground text colors. This is great, but limiting at the same time. If you wanted to have your own custom palette that matches your branding, you would be out of luck. We recognize this is a problem, so we invented an algorithm that would generate Material-like palettes from base colors you provide. Even more, we also generate contrast text colors for each hue in the palette.
14-
15-
#### Themes
16-
17-
The second concept is the one of themes. Palettes, wouldn't do much good if they weren't used by a theme. So we have themes for each component, and a global one, that styles the entire application and every component in it. You simply pass your generated palette to the global theme, we take care of the rest. You can, of course, style each component individually to your liking. We will take a closer look at how to do that later in this article.
18-
19-
#### Typography
20-
21-
The last concept revolves around typography. Although we have a default typeface choice, we really want to give you the power to style your application in every single way. Typography is such an important part of that. We provide a method for changing the font family, the sizes and weights for headings, subheadings and paragraph texts in your app.
22-
23-
### Generating Color Palettes
24-
25-
Our theming library is based on Sass. If you used the **<a href="https://github.com/IgniteUI/igniteui-cli" target="_blank">Ignite UI CLI</a>** to bootstrap your app, you can specify the style extentsion in the **angular-cli.json** config to _scss_, the CLI will take care of compiling the Sass styles for you. If you haven't used Ignite UI CLI then you have to configure your builder to compile Sass styles for you.
26-
27-
Our palettes accept arguments for `primary`, `secondary`, `info`, `success`, `warn`, and `error` colors. The primary color is the one that will be the more prominent color throughout your application. The secondary color is the one used on elements that are actionable, such as buttons, switches, sliders, etc. The only required arguments we require, though, are the ones for `primary` and `secondary` colors. We default the ones for `info`, `success`, `warn`, and `error` to a predefined set of our choosing.
28-
29-
To get started with our first color palette, create an _scss_ file that would be the base file for your global theme. I will call mine _"my-app-theme.scss"_.
30-
31-
```scss
32-
// Import the IgniteUI themes library first
33-
@import "~igniteui-angular/core/styles/themes/index";
34-
35-
$company-color: #2ab759; // Some green shade I like
36-
$secondary-color: #f96a88; // Watermelon pink
37-
38-
$my-color-palette: igx-palette(
39-
$primary: $company-color,
40-
$secondary: $secondary-color
41-
);
42-
```
43-
44-
Now we have a palette, that contains exactly 74 colors! Whoa, wait, what? How did that happen? You provided 2 and got 74? Where did the other 72 colors come from?
45-
Let's stop here to explain what just happened as it's quite important. When you provided `primary` and `secondary` colors, we took those and generated shades and accent colors for each one. Basically now in your palette you have 2 sub-palettes for `primary` and `secondary` colors. Each sub-palette contains 12 additional color variations based on the original color. 4 of the 12 colors are lighter shades of your original color, and 4 are darker. The remaining 4 colors are more exaggerated 'accent' versions of the original color. With the original color that makes for a total of 13 colors in each palette.
46-
47-
With so many colors in each sub-palette you may be wondering, how on Earth will I know which one is which, right? It's quite simple, really. Each of the colors in the sub-palette has a number. We assign the number `500` to the original color. The lighter shades start from `100` and range to `400`. The darker shades start from `600` and range to `900`. The accent colors have string names `A100`, `A200`, `A400`, and `A700`, respectively. Okay, but now that's only 26 out of 72. Don't worry, there's another sub-palette we give you. One that consists of gray 'colors', called `grays`. It's just like the other two color sub-palettes, but doesn't include any accent variations. Good, now we're up to 26 + 9 for a total of 35 colors. That is still a long way from 74. Where do the other 39 colors come from? Let's solve the final puzzle. Remember you can also have 4 additonional colors for `info`, `success`, `warn` and `error`. So that leaves another 35 colors unaccounted for. Remember the count for the `primary`, `secondary`, and `grays` sub-palettes was exactly 35? The other 35 remaining colors are contrast text colors for each of the colors in the `primary`, `secondary`, and `grays` sub-palettes.
48-
49-
Got it? Good! But how does one access any of the colors in the palette?
50-
51-
#### Getting Sub-Palette Colors
52-
53-
We provide a function that is easy to remember and use `igx-color`. It takes three arguments - `palette`, `color`, and `variant`;
54-
55-
```scss
56-
$my-primary-600: igx-color($my-palette, "primary", 600);
57-
$my-primary-A700: igx-color($my-palette, "secondary", "A700");
58-
$my-warning-color: igx-color($my-palette, "warn");
59-
// sample usage
60-
61-
.my-awesome-class {
62-
background: $my-primary-600;
63-
border-color: $my-primary-A700;
64-
}
65-
66-
.warning-bg {
67-
background: $my-warning-color;
68-
}
69-
```
8+
The Ignite UI for Angular theming library is based on [**Sass**](https://sass-lang.com). If you used the **<a href="https://github.com/IgniteUI/igniteui-cli" target="_blank">Ignite UI CLI</a>** to bootstrap your app, you can specify the style in the **angular.json** config to _scss_, the CLI will take care of compiling the Sass styles for you. If you haven't used Ignite UI CLI then you have to configure your builder to compile Sass styles for you.
709

71-
#### Getting Contrast Text Colors
10+
### Palettes
7211

73-
Similar to how we get sub-palette colors, there's a way to get the contrast text color for each of the colors in the sub-palettes.
12+
The first concept is the one of palettes of colors. As in any visual tool, colors are the main differentiating factor between one application and another. The Material Design Guidelines prescribe predefined palettes of colors that range in hue and lightness for a base color. There's a good reason for that. They really want to ensure good color matching and contrast between the background colors and the foreground text colors. This is great, but limiting at the same time. If you wanted to have your own custom palette that matches your branding, you would be out of luck. We recognize this is a problem, so we invented an algorithm that would generate Material-like palettes from base colors you provide. Even more, we also generate contrast text colors for each hue in the palette.
7413

75-
```scss
76-
$my-primary-800: igx-color($my-palette, "primary", 600);
77-
$my-primary-800-text: igx-contrast-color($my-palette, "primary", 600);
78-
// sample usage
7914

80-
.my-awesome-article {
81-
background: $my-primary-800;
82-
color: $my-primary-800-text;
83-
}
84-
```
15+
### Schemas
8516

86-
### Generating a Theme
17+
The second important concept revolves around theme schemas. Theme schemas are like recipes for component themes. They give inidual component themes information about colors, margins, paddings, etc. For instance, a component scheme tells a component theme that the background color for an element should be the `500` variant from the `primary` palette, without caring what palette the user passes to the component theme.
8718

88-
If you've included the _"igniteui-angular.css"_ file in your application project, now is a good time to remove it. We are going to use our own _"my-app-theme.scss"_ file to generate our own theme.
8919

90-
Let's start from our very first example on this page. This time, though, we're going to be including two mixins `igx-core` and `igx-theme`; For now `igx-core` doesn't accept any arguments. `igx-theme`, however, does accept 2 - `$palette` and `$exclude`. For now, we'll only talk about the `$palette` argument. We'll take a deeper look at what `$exclude` does later on when we talk about individual component themes.
20+
### Themes
9121

92-
```scss
93-
// Import the IgniteUI themes library first
94-
@import "~igniteui-angular/lib/core/styles/themes/index";
22+
Finally, we have component themes. Palettes and Schemas wouldn't do much good on their own if they weren't used by a theme. We have themes for inidual component, and a global one, that styles the entire application and every component in it. You simply pass a palette and a schema to the global theme, we take care of the rest. You can, of course, style each component individually to your liking.
9523

96-
$company-color: #2ab759; // Some green shade I like
97-
$secondary-color: #f96a88; // Watermelon pink
24+
### Typography
9825

99-
$my-color-palette: igx-palette(
100-
$primary: $company-color,
101-
$secondary: $secondary-color
102-
);
26+
Typography is a separate module in our Sass theming framework, which is decoupled from the component themes. Although we have a default typeface of choice, we really want to give you the power to style your application in every single way. Typography is such an important part of that. We provide a method for changing the font family, the sizes and weights for headings, subheadings, buttons, body text, etc. in your app.
10327

104-
// IMPORTANT: Make sure you always include igx-core first!
105-
@include igx-core();
106-
// Pass the color palette we generated to the igx-theme mixin
107-
@include igx-theme($my-color-palette);
108-
```
28+
### Additional Resources
10929

110-
That's it. Your application will now use the colors from your newly generated palette.
30+
Learn how to create themes:
11131

112-
### Customizing Typography (WIP)
32+
* [Global Themes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/global-theme.html)
33+
* [Component Themes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/component-themes.html)
11334

114-
In its current state, the defining custom typography is limited to changing the `font family` of the application. We'll be updating this functionallity with subsequent releases. Our intent is to provide a robust way to customize the typography in your application.
35+
Learn how to create a component schema:
36+
* [Schemas](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/schemas.html)
11537

116-
To customize the typography use the `igx-typography` mixin. It takes exactly one argument - `config`.
38+
Learn how to build color palettes:
39+
* [Palettes](https://www.infragistics.com/products/ignite-ui-angular/angular/components/themes/palette.html)
11740

118-
```scss
119-
// Import the IgniteUI themes library first
120-
@import "~igniteui-angular/core/styles/themes/index";
121-
// IMPORTANT: Make sure you always include igx-core first!
122-
@include igx-core();
123-
@include igx-theme($default-theme);
41+
Our community is active and always welcoming to new ideas.
12442

125-
//Include after igx-core
126-
@include igx-typography($config: (font-family: "Comic Sans MS"));
127-
```
43+
* [Ignite UI for Angular **Forums**](https://www.infragistics.com/community/forums/f/ignite-ui-for-angular)
44+
* [Ignite UI for Angular **GitHub**](https://github.com/IgniteUI/igniteui-angular)

‎projects/igniteui-angular/src/lib/core/styles/themes/schemas/dark/_tooltip.scss‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
/// @author <a href="https://github.com/desig9stein" target="_blank">Marin Popov</a>
66
////
77

8-
/// Generates a light tooltip schema.
8+
/// Generates a dark tooltip schema.
99
/// @type {Map}
1010
/// @requires {function} extend
1111
/// @requires $_light-tooltip

0 commit comments

Comments
 (0)