From 20808ee92d4ce177711bea18643b8d7f86071523 Mon Sep 17 00:00:00 2001
From: Shane Eckenrode <sue2@psu.edu>
Date: Fri, 31 Jan 2020 11:56:26 -0500
Subject: [PATCH] Add initial documentation for alternate theming

---
 libs/utils/theming/README.md | 124 ++++++++++++++++++++++++++++++++++-
 1 file changed, 121 insertions(+), 3 deletions(-)

diff --git a/libs/utils/theming/README.md b/libs/utils/theming/README.md
index 74e9cb6..f723d44 100644
--- a/libs/utils/theming/README.md
+++ b/libs/utils/theming/README.md
@@ -1,7 +1,125 @@
 # utils-theming
 
-This library was generated with [Nx](https://nx.dev).
+# Setup for Alternate Theming
 
-## Running unit tests
+## Prerequisites
 
-Run `nx test utils-theming` to execute the unit tests.
+- Install @psu/components, @psu/utils, @psu/palette
+- Install node-sass and node-sass-tilde-importer as Dev Dependencies
+- Application must be setup to use scss and recommended to adhere to the following scss styling structure
+
+  - If not already existing, you must have the following files within the src directory at the **_root of the application_**
+
+    - `_app-theme.scss`: Import all application, internal application libraries, or external libraries that have theming here and include them within a mixin named `@mixin app-theme($theme)`.
+    - `_theme.scss`: Set up the primary application theme variables here. This file should import the theme palette from `@psu/palette` and set up the base theme colors. It should follow the structure from the snippet below
+
+    ```scss
+    @import '~@psu/palette/beaver-blue';
+
+    // Setting Theme Colors
+    $primaryPalette: mat-palette($primary, 700, 50, 900);
+    $secondaryPalette: mat-palette($secondary);
+    $errorPalette: mat-palette($error);
+    $appBackground: #f5f5f5;
+    ```
+
+    - `_typography.scss`: Set up the application typography variables here. Follow the structure from the snippet below. More information can be found in the [typography section](https://git.psu.edu/ais-swe/ux/theme-lib#typography) of the theme utils readme.
+
+    ```scss
+    // Setting Typography for all themes
+    $titleFont: 'Roboto Slab';
+    $bodyFont: 'Open Sans';
+
+    $titleRegularWeight: 400;
+    $titleBoldWeight: 700;
+    $bodyRegularWeight: 400;
+    $bodyBoldWeight: 600;
+    ```
+
+  - Import each of the above files into `styles.scss` and follow instructions for [theme generation](https://git.psu.edu/ais-swe/ux/theme-lib#theming) and [typography generation](https://git.psu.edu/ais-swe/ux/theme-lib#typography) from theme utils readme.
+
+## Application-Specific Setup
+
+1. Copy the following snippet into a new file named `build-themes.sh` and place in the `tools` directory. The tools directory should be located at the root of the project.
+
+```sh
+#!/bin/bash
+
+DEST_PATH=apps/ui/src/assets
+INPUT_PATH=$DEST_PATH/alternate-themes/
+
+
+echo Building custom theme scss files.
+
+# Get the files
+FILES=$(find apps/ui/src/assets/alternate-themes -name "*.scss")
+
+for FILE in $FILES
+do
+  FILENAME=${FILE#$INPUT_PATH}
+  BASENAME=${FILENAME%.scss}
+  $(npm bin)/node-sass --importer=node_modules/node-sass-tilde-importer $FILE > $DEST_PATH/$BASENAME.css
+done
+
+echo Finished building CSS.
+```
+
+2. Create the `alternate-themes` directory at the path `apps/ui/src/assets`. This is where you will add your alternate theme scss files. These scss files should follow the following structure:
+
+```scss
+@import '~@psu/theme-lib/md2/md2'; // Import the theming utilities
+@import '~@psu/palette/nittany-navy'; // Import the alternate theme palette
+@import '../../app-theme'; // Import the app-theme mixin to propagate the alternate theme to all angular material, application, and library components
+
+// Setting Theme Colors
+$primaryPalette: mat-palette($primary, 700, 50, 900);
+$secondaryPalette: mat-palette($secondary);
+$errorPalette: mat-palette($error);
+$appBackground: #f5f5f5;
+
+// Generate the new alternate theme and propagate it to all components
+$theme: generate-material-light-theme(
+  $primaryPalette,
+  $secondaryPalette,
+  $errorPalette,
+  $status-colors,
+  $appBackground-light
+);
+@include angular-material-theme($theme);
+@include app-theme($theme);
+```
+
+3. In the `angular.json`, add the following code to the assets array of the application's build object. Path should be close to: `projects`
+
+```json
+{
+  "glob": "*.css",
+  "input": "apps/ui/src/assets",
+  "output": "./alt-themes/"
+}
+```
+
+4. Add the `build-themes` script to the package.json and update existing scripts to call that script first.
+5. Add the `STYLE_MANAGER_CONFIG` to `app.module.ts`'s providers array. Ex:
+
+```ts
+{
+  provide: STYLE_MANAGER_CONFIG,
+  useValue: [
+    {
+      name: 'beaver-blue',
+      primary: '#316cae',
+      isDefault: true
+    },
+    {
+      name: 'nittany-navy',
+      primary: '#143372'
+    },
+    {
+      name: 'dark',
+      primary: '#0d0d0d',
+      isDark: true
+    }
+  ]
+}
+```
-- 
GitLab