add system variables guide (#1287)

* add system variables guide * use static style bindings --------- Co-authored-by: Andrew Seguin <[email protected]>
angular · Nov 7, 2024 · bdda34c · bdda34c
1 parent ac859c2
commit bdda34c
Show file tree

Hide file tree

Showing 13 changed files with 671 additions and 15 deletions.
diff --git a/src/app/pages/component-viewer/component-api.html b/src/app/pages/component-viewer/component-api.html
@@ -9,14 +9,14 @@
   same container so that they display one after another.
   -->
   <div class="docs-component-api">
-    <doc-viewer [documentUrl]="getApiDocumentUrl(docItem)"
+    <doc-viewer [document]="getApiDocumentUrl(docItem)"
       class="docs-component-view-text-content"
       (contentRendered)="updateTableOfContents(docItem.name, $event)">
     </doc-viewer>
 
     @for (additionalApiDoc of docItem.additionalApiDocs; track additionalApiDoc) {
       <doc-viewer
-        documentUrl="/docs-content/api-docs/{{additionalApiDoc.path}}"
+        document="/docs-content/api-docs/{{additionalApiDoc.path}}"
         class="docs-component-view-text-content"
         (contentRendered)="updateTableOfContents(additionalApiDoc.name, $event, $index + 1)"/>
     }

diff --git a/src/app/pages/component-viewer/component-overview.html b/src/app/pages/component-viewer/component-overview.html
@@ -2,7 +2,7 @@
   <h2 class="cdk-visually-hidden" tabindex="-1">
     Overview for {{docItem.id}}
   </h2>
-  <doc-viewer [documentUrl]="getOverviewDocumentUrl(docItem)"
+  <doc-viewer [document]="getOverviewDocumentUrl(docItem)"
       class="docs-component-view-text-content docs-component-overview"
       (contentRendered)="updateTableOfContents('Overview Content', $event)">
   </doc-viewer>

diff --git a/src/app/pages/guide-viewer/guide-viewer.html b/src/app/pages/guide-viewer/guide-viewer.html
@@ -2,7 +2,7 @@
   <div class="docs-guide-toc-and-content">
     <doc-viewer class="docs-guide-content"
                 (contentRendered)="toc.addHeaders('Guide Content', $event); toc.updateScrollPosition()"
-                [documentUrl]="guide?.document"
+                [document]="guide?.document"
                 focusOnNavigation
                 id="guide-content"
                 aria-label="Guide content"></doc-viewer>

diff --git a/src/app/pages/system-variables/index.ts b/src/app/pages/system-variables/index.ts
@@ -0,0 +1 @@
+export * from './system-variables';
diff --git a/src/app/pages/system-variables/system-variables.html b/src/app/pages/system-variables/system-variables.html
@@ -0,0 +1,242 @@
+<p>
+  Angular Material components depend on system variables defined as CSS variables through the
+  <span class="demo-surface-variable">material.theme</span>
+  Sass mixin. This page provides guidance and documentation for using these variables to
+  customize components.
+</p>
+
+<h2 id="colors">Colors</h2>
+
+<p>
+  Material Design uses color to create accessible, personal color schemes
+  that communicate your product's hierarchy, state, and brand. See Material
+  Design's <a href="https://m3.material.io/styles/color/system/overview">Color System</a>
+  page to learn more about its use and purpose.
+</p>
+<p>
+  The following colors are the most often used in Angular Material components. Use these
+  colors and follow their uses to add theme colors to your application's custom components.
+</p>
+
+<div class="demo-group">
+  <div class="demo-color-container">
+    <div class="demo-heading"
+         style="background-color: var(--mat-sys-primary);
+                color: var(--mat-sys-on-primary)">
+      <div class="demo-name">Primary</div>
+      <div class="demo-variable demo-code">--mat-sys-primary</div>
+    </div>
+    <div class="demo-description">
+      <p>
+        The most common color used by Angular Material components to
+        participate in the application theme.
+      </p>
+      <p>
+        Examples include the background color
+        of filled buttons, the icon color of selected radio buttons, and the
+        outline color of form fields.
+      </p>
+      <p>
+        Use the color <span class="demo-surface-variable">--mat-sys-on-primary</span> for
+        icons, text, and other visual elements placed on a primary background. This
+        color is calculated to be optimal for accessibility and legibility.
+      </p>
+    </div>
+  </div>
+
+  <div class="demo-color-container">
+    <div class="demo-heading"
+         style="background-color: var(--mat-sys-surface);
+                color: var(--mat-sys-on-surface)">
+      <div class="demo-name">Surface</div>
+      <div class="demo-variable code">--mat-sys-surface</div>
+    </div>
+    <div class="demo-description">
+      <p>
+        A low-emphasis background color that provides a clear contrast for
+        both light and dark themes and their varied theme colors.
+      </p>
+      <p>
+        Examples include the background color of the application and most
+        components such as the dialog, card, table, and more.
+      </p>
+      <p>
+        Use the color <span class="demo-surface-variable">--mat-sys-on-surface</span> for
+        icons, text, and other visual elements placed on a surface background. This
+        color is calculated to be optimal for accessibility and legibility.
+      </p>
+    </div>
+  </div>
+
+  <div class="demo-color-container">
+    <div class="demo-heading"
+         style="background-color: var(--mat-sys-error);
+                color: var(--mat-sys-on-error)">
+      <div class="demo-name">Error</div>
+      <div class="demo-variable demo-code">--mat-sys-error</div>
+    </div>
+    <div class="demo-description">
+      <p>
+        High-contrast color meant to alert the user to attract immediate attention.
+      </p>
+      <p>
+        Examples include the background color of the badge and the text color of invalid
+        form fields inputs.
+      </p>
+      <p>
+        Use the color <span class="demo-surface-variable">--mat-sys-on-error</span> for
+        icons, text, and other visual elements placed on an error background. This
+        color is calculated to be optimal for accessibility and legibility.
+      </p>
+    </div>
+  </div>
+
+  <div class="demo-color-container">
+    <div class="demo-heading"
+         style="background-color: var(--mat-sys-outline);
+                color: var(--mat-sys-surface)">
+      <div class="demo-name">Outline</div>
+      <div class="demo-variable demo-code">--mat-sys-outline </div>
+    </div>
+    <div class="demo-description">
+      <p>
+        Used for borders and dividers to help provide visual separation between
+        and around elements.
+      </p>
+      <p>
+        Examples include the color of the divider and border color of an outlined
+        form field.
+      </p>
+      <p>
+        Use the color <span class="demo-surface-variable">--mat-sys-outline-variant</span> for a less
+        prominent outline.
+      </p>
+    </div>
+  </div>
+</div>
+
+<mat-expansion-panel>
+  <mat-expansion-panel-header>Other available colors</mat-expansion-panel-header>
+
+  <p>
+    These colors are less commonly used in Angular Material components but
+    are available for adding color variety and creating additional emphasis
+    to components.
+  </p>
+  <p>
+    Colors may be paired with a <span class="demo-surface-variable">--mat-sys-on-</span> variable
+    that should be used for text and icons placed within a filled container.
+  </p>
+
+  <h2>Alternative Theme Colors</h2>
+
+  <theme-demo-colors [colors]="alternativeThemeColors"></theme-demo-colors>
+
+  <h2>Surface Colors</h2>
+
+  <p>
+    The following colors should be used for backgrounds and large,
+    low-emphasis areas of the screen.
+  </p>
+
+  <p>
+    Containers filled with a surface color should apply the
+    <span class="demo-surface-variable">--mat-sys-on-surface</span> color to text
+    and icons placed within.
+  </p>
+
+  <theme-demo-colors [colors]="surfaceColors"></theme-demo-colors>
+
+  <h2>Fixed Colors</h2>
+
+  <p>
+    These colors are the same for both light and dark themes. They are unused
+    by any Angular Material components.
+  </p>
+
+  <theme-demo-colors [colors]="fixedColors"></theme-demo-colors>
+
+</mat-expansion-panel>
+
+<h2 id="typography">Typography</h2>
+
+<p>
+  There are five categories of font types defined by Material Design: body, display, headline,
+  label, and title. Each category has three sizes: small, medium, and large.
+</p>
+<p>
+  Learn more about how these categories and their sizes should be used in your application by
+  visiting Material Design's
+  <a href="https://m3.material.io/styles/typography/overview">Typography</a> documentation.
+</p>
+
+
+@for (category of ['body', 'display', 'headline', 'label', 'title']; track $index) {
+  <div class="demo-typography-group">
+    <div class="demo-typography-title">{{category}}</div>
+    @for (size of ['small', 'medium', 'large']; track $index) {
+      <div class="demo-typography-example">
+        <div class="demo-typography-variable">
+          <div class="demo-surface-variable">--mat-sys-{{category}}-{{size}}</div>
+        </div>
+        <div class="demo-typography-text" [style.font]="'var(--mat-sys-' + category + '-' + size + ')'">Lorem ipsum dolor</div>
+      </div>
+    }
+  </div>
+}
+
+<p>
+  Each system variable can be applied to the "font" CSS style. Additionally, the parts of the variable definition
+  can be accessed individually by appending the keywords "font", "line-height", "size", "tracking", and "weight".
+</p>
+<p>
+  For example, the values for medium body text may be defined as follows:
+</p>
+<pre class="demo-code-block">
+--mat-sys-body-medium: 400 0.875rem / 1.25rem Roboto, sans-serif;
+--mat-sys-body-medium-font: Roboto, sans-serif;
+--mat-sys-body-medium-line-height: 1.25rem;
+--mat-sys-body-medium-size: 0.875rem;
+--mat-sys-body-medium-tracking: 0.016rem;
+--mat-sys-body-medium-weight: 400;
+</pre>
+
+<h2 id="elevation">Elevation</h2>
+
+<p>
+  Material Design provides six levels of elevation that can be used to provide
+  a sense of depth and organization to an application's UI. Learn more at Material Design's
+  <a href="https://m3.material.io/styles/elevation/overview">Elevation</a> guide.
+</p>
+
+<p>
+  These levels are defined as CSS box-shadow values that can be styled to an element.
+</p>
+
+@for (level of [0, 1, 2, 3, 4, 5]; track $index) {
+  <div class="demo-elevation code" [style.box-shadow]="'var(--mat-sys-level' + level + ')'">
+    box-shadow: var(--mat-sys-level{{level}})
+  </div>
+}
+
+<h2 id="overrides">Overrides</h2>
+
+<p>
+  The <span class="demo-surface-variable">mat.theme-overrides</span> mixin
+  can be included to emit different definitions for the system variables and
+  override the definitions emitted from <span class="demo-surface-variable">mat.theme</span>.
+</p>
+
+<div class="demo-overrides">
+  This example container has several system variables overridden by including the
+  following Sass code:
+
+  <pre>
+  &#64;include mat.theme-overrides((
+    primary: #ebdcff,
+    on-primary: #230f46,
+    body-medium: 500 1.15rem/1.3rem Arial,
+    corner-large: 32px,
+    level3: 0 4px 6px 1px var(--mat-sys-surface-dim),
+  ));</pre>
+</div>