Skip to content
This repository was archived by the owner on Dec 18, 2024. It is now read-only.

Commit bdda34c

Browse files
andrewseguinAndrew Seguin
andrewseguin
and
Andrew Seguin
authored
add system variables guide (#1287)
* add system variables guide * use static style bindings --------- Co-authored-by: Andrew Seguin <andrewseguin@google.com>
1 parent ac859c2 commit bdda34c

File tree

13 files changed

+671
-15
lines changed

13 files changed

+671
-15
lines changed

‎src/app/pages/component-viewer/component-api.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,14 @@
99
same container so that they display one after another.
1010
-->
1111
<div class="docs-component-api">
12-
<doc-viewer [documentUrl]="getApiDocumentUrl(docItem)"
12+
<doc-viewer [document]="getApiDocumentUrl(docItem)"
1313
class="docs-component-view-text-content"
1414
(contentRendered)="updateTableOfContents(docItem.name, $event)">
1515
</doc-viewer>
1616

1717
@for (additionalApiDoc of docItem.additionalApiDocs; track additionalApiDoc) {
1818
<doc-viewer
19-
documentUrl="/docs-content/api-docs/{{additionalApiDoc.path}}"
19+
document="/docs-content/api-docs/{{additionalApiDoc.path}}"
2020
class="docs-component-view-text-content"
2121
(contentRendered)="updateTableOfContents(additionalApiDoc.name, $event, $index + 1)"/>
2222
}

‎src/app/pages/component-viewer/component-overview.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<h2 class="cdk-visually-hidden" tabindex="-1">
33
Overview for {{docItem.id}}
44
</h2>
5-
<doc-viewer [documentUrl]="getOverviewDocumentUrl(docItem)"
5+
<doc-viewer [document]="getOverviewDocumentUrl(docItem)"
66
class="docs-component-view-text-content docs-component-overview"
77
(contentRendered)="updateTableOfContents('Overview Content', $event)">
88
</doc-viewer>

‎src/app/pages/guide-viewer/guide-viewer.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<div class="docs-guide-toc-and-content">
33
<doc-viewer class="docs-guide-content"
44
(contentRendered)="toc.addHeaders('Guide Content', $event); toc.updateScrollPosition()"
5-
[documentUrl]="guide?.document"
5+
[document]="guide?.document"
66
focusOnNavigation
77
id="guide-content"
88
aria-label="Guide content"></doc-viewer>

‎src/app/pages/system-variables/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export * from './system-variables';

‎src/app/pages/system-variables/system-variables.html

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
<p>
2+
Angular Material components depend on system variables defined as CSS variables through the
3+
<span class="demo-surface-variable">material.theme</span>
4+
Sass mixin. This page provides guidance and documentation for using these variables to
5+
customize components.
6+
</p>
7+
8+
<h2 id="colors">Colors</h2>
9+
10+
<p>
11+
Material Design uses color to create accessible, personal color schemes
12+
that communicate your product's hierarchy, state, and brand. See Material
13+
Design's <a href="https://m3.material.io/styles/color/system/overview">Color System</a>
14+
page to learn more about its use and purpose.
15+
</p>
16+
<p>
17+
The following colors are the most often used in Angular Material components. Use these
18+
colors and follow their uses to add theme colors to your application's custom components.
19+
</p>
20+
21+
<div class="demo-group">
22+
<div class="demo-color-container">
23+
<div class="demo-heading"
24+
style="background-color: var(--mat-sys-primary);
25+
color: var(--mat-sys-on-primary)">
26+
<div class="demo-name">Primary</div>
27+
<div class="demo-variable demo-code">--mat-sys-primary</div>
28+
</div>
29+
<div class="demo-description">
30+
<p>
31+
The most common color used by Angular Material components to
32+
participate in the application theme.
33+
</p>
34+
<p>
35+
Examples include the background color
36+
of filled buttons, the icon color of selected radio buttons, and the
37+
outline color of form fields.
38+
</p>
39+
<p>
40+
Use the color <span class="demo-surface-variable">--mat-sys-on-primary</span> for
41+
icons, text, and other visual elements placed on a primary background. This
42+
color is calculated to be optimal for accessibility and legibility.
43+
</p>
44+
</div>
45+
</div>
46+
47+
<div class="demo-color-container">
48+
<div class="demo-heading"
49+
style="background-color: var(--mat-sys-surface);
50+
color: var(--mat-sys-on-surface)">
51+
<div class="demo-name">Surface</div>
52+
<div class="demo-variable code">--mat-sys-surface</div>
53+
</div>
54+
<div class="demo-description">
55+
<p>
56+
A low-emphasis background color that provides a clear contrast for
57+
both light and dark themes and their varied theme colors.
58+
</p>
59+
<p>
60+
Examples include the background color of the application and most
61+
components such as the dialog, card, table, and more.
62+
</p>
63+
<p>
64+
Use the color <span class="demo-surface-variable">--mat-sys-on-surface</span> for
65+
icons, text, and other visual elements placed on a surface background. This
66+
color is calculated to be optimal for accessibility and legibility.
67+
</p>
68+
</div>
69+
</div>
70+
71+
<div class="demo-color-container">
72+
<div class="demo-heading"
73+
style="background-color: var(--mat-sys-error);
74+
color: var(--mat-sys-on-error)">
75+
<div class="demo-name">Error</div>
76+
<div class="demo-variable demo-code">--mat-sys-error</div>
77+
</div>
78+
<div class="demo-description">
79+
<p>
80+
High-contrast color meant to alert the user to attract immediate attention.
81+
</p>
82+
<p>
83+
Examples include the background color of the badge and the text color of invalid
84+
form fields inputs.
85+
</p>
86+
<p>
87+
Use the color <span class="demo-surface-variable">--mat-sys-on-error</span> for
88+
icons, text, and other visual elements placed on an error background. This
89+
color is calculated to be optimal for accessibility and legibility.
90+
</p>
91+
</div>
92+
</div>
93+
94+
<div class="demo-color-container">
95+
<div class="demo-heading"
96+
style="background-color: var(--mat-sys-outline);
97+
color: var(--mat-sys-surface)">
98+
<div class="demo-name">Outline</div>
99+
<div class="demo-variable demo-code">--mat-sys-outline </div>
100+
</div>
101+
<div class="demo-description">
102+
<p>
103+
Used for borders and dividers to help provide visual separation between
104+
and around elements.
105+
</p>
106+
<p>
107+
Examples include the color of the divider and border color of an outlined
108+
form field.
109+
</p>
110+
<p>
111+
Use the color <span class="demo-surface-variable">--mat-sys-outline-variant</span> for a less
112+
prominent outline.
113+
</p>
114+
</div>
115+
</div>
116+
</div>
117+
118+
<mat-expansion-panel>
119+
<mat-expansion-panel-header>Other available colors</mat-expansion-panel-header>
120+
121+
<p>
122+
These colors are less commonly used in Angular Material components but
123+
are available for adding color variety and creating additional emphasis
124+
to components.
125+
</p>
126+
<p>
127+
Colors may be paired with a <span class="demo-surface-variable">--mat-sys-on-</span> variable
128+
that should be used for text and icons placed within a filled container.
129+
</p>
130+
131+
<h2>Alternative Theme Colors</h2>
132+
133+
<theme-demo-colors [colors]="alternativeThemeColors"></theme-demo-colors>
134+
135+
<h2>Surface Colors</h2>
136+
137+
<p>
138+
The following colors should be used for backgrounds and large,
139+
low-emphasis areas of the screen.
140+
</p>
141+
142+
<p>
143+
Containers filled with a surface color should apply the
144+
<span class="demo-surface-variable">--mat-sys-on-surface</span> color to text
145+
and icons placed within.
146+
</p>
147+
148+
<theme-demo-colors [colors]="surfaceColors"></theme-demo-colors>
149+
150+
<h2>Fixed Colors</h2>
151+
152+
<p>
153+
These colors are the same for both light and dark themes. They are unused
154+
by any Angular Material components.
155+
</p>
156+
157+
<theme-demo-colors [colors]="fixedColors"></theme-demo-colors>
158+
159+
</mat-expansion-panel>
160+
161+
<h2 id="typography">Typography</h2>
162+
163+
<p>
164+
There are five categories of font types defined by Material Design: body, display, headline,
165+
label, and title. Each category has three sizes: small, medium, and large.
166+
</p>
167+
<p>
168+
Learn more about how these categories and their sizes should be used in your application by
169+
visiting Material Design's
170+
<a href="https://m3.material.io/styles/typography/overview">Typography</a> documentation.
171+
</p>
172+
173+
174+
@for (category of ['body', 'display', 'headline', 'label', 'title']; track $index) {
175+
<div class="demo-typography-group">
176+
<div class="demo-typography-title">{{category}}</div>
177+
@for (size of ['small', 'medium', 'large']; track $index) {
178+
<div class="demo-typography-example">
179+
<div class="demo-typography-variable">
180+
<div class="demo-surface-variable">--mat-sys-{{category}}-{{size}}</div>
181+
</div>
182+
<div class="demo-typography-text" [style.font]="'var(--mat-sys-' + category + '-' + size + ')'">Lorem ipsum dolor</div>
183+
</div>
184+
}
185+
</div>
186+
}
187+
188+
<p>
189+
Each system variable can be applied to the "font" CSS style. Additionally, the parts of the variable definition
190+
can be accessed individually by appending the keywords "font", "line-height", "size", "tracking", and "weight".
191+
</p>
192+
<p>
193+
For example, the values for medium body text may be defined as follows:
194+
</p>
195+
<pre class="demo-code-block">
196+
--mat-sys-body-medium: 400 0.875rem / 1.25rem Roboto, sans-serif;
197+
--mat-sys-body-medium-font: Roboto, sans-serif;
198+
--mat-sys-body-medium-line-height: 1.25rem;
199+
--mat-sys-body-medium-size: 0.875rem;
200+
--mat-sys-body-medium-tracking: 0.016rem;
201+
--mat-sys-body-medium-weight: 400;
202+
</pre>
203+
204+
<h2 id="elevation">Elevation</h2>
205+
206+
<p>
207+
Material Design provides six levels of elevation that can be used to provide
208+
a sense of depth and organization to an application's UI. Learn more at Material Design's
209+
<a href="https://m3.material.io/styles/elevation/overview">Elevation</a> guide.
210+
</p>
211+
212+
<p>
213+
These levels are defined as CSS box-shadow values that can be styled to an element.
214+
</p>
215+
216+
@for (level of [0, 1, 2, 3, 4, 5]; track $index) {
217+
<div class="demo-elevation code" [style.box-shadow]="'var(--mat-sys-level' + level + ')'">
218+
box-shadow: var(--mat-sys-level{{level}})
219+
</div>
220+
}
221+
222+
<h2 id="overrides">Overrides</h2>
223+
224+
<p>
225+
The <span class="demo-surface-variable">mat.theme-overrides</span> mixin
226+
can be included to emit different definitions for the system variables and
227+
override the definitions emitted from <span class="demo-surface-variable">mat.theme</span>.
228+
</p>
229+
230+
<div class="demo-overrides">
231+
This example container has several system variables overridden by including the
232+
following Sass code:
233+
234+
<pre>
235+
&#64;include mat.theme-overrides((
236+
primary: #ebdcff,
237+
on-primary: #230f46,
238+
body-medium: 500 1.15rem/1.3rem Arial,
239+
corner-large: 32px,
240+
level3: 0 4px 6px 1px var(--mat-sys-surface-dim),
241+
));</pre>
242+
</div>

0 commit comments

Comments
 (0)