diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index dc2a35a27..000000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,85 +0,0 @@ -version: 2.1 -orbs: - browser-tools: circleci/browser-tools@1.4.8 -jobs: - build: - docker: - - image: cimg/node:18.17.1-browsers - working_directory: ~/doc-it-dev - environment: - - MASTER_BRANCH: master - - DEV_BRANCH: dev - - DEV_TARGET: https://github.com/brightlayer-ui-dev/brightlayer-ui-dev.github.io - - MASTER_TARGET: https://github.com/brightlayer-ui/brightlayer-ui.github.io - - GH_EMAIL: brightlayer-ui@eaton.com - - GH_NAME: Brightlayer UI Agent - steps: - - checkout - - browser-tools/install-browser-tools - - restore_cache: - keys: - - v3-dependencies-{{ checksum "package.json" }} - - run: - name: Install dependencies - command: | - yarn install - yarn upgrade @brightlayer-ui/icons-mui - - save_cache: - paths: - - node_modules - key: v3-dependencies-{{ checksum "package.json" }} - - run: - name: Prettier Check - command: | - yarn prettier:check - - run: - name: Lint - command: yarn lint - - run: - name: Run tests - command: yarn test - - run: - name: Verify Markdown Hyperlinks - command: | - yarn check:links-ci - # - run: - # name: Run Cypress - # command: | - # if [ $CIRCLE_BRANCH == $MASTER_BRANCH ] || [ $CIRCLE_BRANCH == $DEV_BRANCH ]; then - # yarn cytest - # fi - - run: - name: Deploy - command: | - if [ $CIRCLE_BRANCH == $MASTER_BRANCH ] || [ $CIRCLE_BRANCH == $DEV_BRANCH ]; then - git config --global user.email "$GH_EMAIL" - git config --global user.name "$GH_NAME" - - if [ $CIRCLE_BRANCH == $MASTER_BRANCH ]; then - git clone $MASTER_TARGET out - else - git clone $DEV_TARGET out - fi - - cd out - git rm -rf . - cd .. - - # Copy the correct Google Analytics files (master/dev) - if [ $CIRCLE_BRANCH == $MASTER_BRANCH ] - then - yarn ga:prod - elif [ $CIRCLE_BRANCH == $DEV_BRANCH ] - then - yarn ga:dev - fi - - yarn build - - cp -a build/. out/. - cd out - - git add -A - git commit -m "Automated deployment to GitHub Pages: ${CIRCLE_SHA1}" --allow-empty - git push - fi diff --git a/.github/workflows/blui-ci.yml b/.github/workflows/blui-ci.yml new file mode 100644 index 000000000..e833b45a2 --- /dev/null +++ b/.github/workflows/blui-ci.yml @@ -0,0 +1,132 @@ +name: Build + +on: + push: + branches: [ "dev", "master" ] + pull_request: + branches: [ "dev", "master" ] + pull_request_target: + types: + - opened + branches: + - '*/*' + +permissions: + pull-requests: write + contents: read + +jobs: + prettier_lint: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [20.x] + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'yarn' + - run: yarn + - run: yarn prettier:check + - run: yarn lint + + test_links: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [20.x] + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'yarn' + - run: yarn + - run: yarn check:links-ci + + build_doc_site: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [20.x] + env: + ga-id: ${{ github.ref == 'refs/heads/master' && 'ga:prod' || 'ga:dev' }} + REACT_APP_DOCIT_GITHUB_TOKEN: ${{ secrets.REACT_APP_DOCIT_GITHUB_TOKEN }} + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Use Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'yarn' + - run: yarn --immutable + - run: yarn ${{env.ga-id}} + - run: yarn build + - name: Save build + uses: actions/upload-artifact@v3 + with: + name: build + if-no-files-found: error + path: build + + deploy_doc_site_dev: + runs-on: ubuntu-latest + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/dev' }} + needs: build_doc_site + env: + DEV_DEPLOY_TOKEN: ${{secrets.DEV_DEPLOY_TOKEN}} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Download build + uses: actions/download-artifact@v3 + with: + name: build + path: build + - name: deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: build + token: ${{env.DEV_DEPLOY_TOKEN}} + repository-name: brightlayer-ui-dev/brightlayer-ui-dev.github.io + branch: master + git-config-name: Brightlayer UI Agent + git-config-email: brightlayer-ui@eaton.com + commit-message: "Automated deployment to GitHub Pages ${{github.sha}}" + + deploy_doc_site_prod: + runs-on: ubuntu-latest + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} + needs: build_doc_site + env: + DEV_DEPLOY_TOKEN: ${{secrets.DEV_DEPLOY_TOKEN}} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Download build + uses: actions/download-artifact@v3 + with: + name: build + path: build + - name: deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: build + token: ${{env.DEV_DEPLOY_TOKEN}} + repository-name: brightlayer-ui/brightlayer-ui.github.io + branch: master + git-config-name: Brightlayer UI Agent + git-config-email: brightlayer-ui@eaton.com + commit-message: "Automated deployment to GitHub Pages ${{github.sha}}" \ No newline at end of file diff --git a/.github/workflows/firebase-hosting-pull-request.yml b/.github/workflows/firebase-hosting-pull-request.yml index dc6b452c9..04e62bdcc 100644 --- a/.github/workflows/firebase-hosting-pull-request.yml +++ b/.github/workflows/firebase-hosting-pull-request.yml @@ -7,6 +7,8 @@ jobs: build_and_preview: if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}' runs-on: ubuntu-latest + env: + REACT_APP_DOCIT_GITHUB_TOKEN: ${{ secrets.REACT_APP_DOCIT_GITHUB_TOKEN }} steps: - uses: actions/checkout@v2 - run: yarn && yarn build diff --git a/README.md b/README.md index d4c1cde86..b1f39379a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Doc-It (a.k.a. brightlayer-ui.github.io) -[![CircleCI](https://circleci.com/gh/etn-ccis/blui-doc-it/tree/master.svg?style=shield&circle-token=fc2656a76d70b4ff9cdc66cccc758c0dfbf89d25)](https://circleci.com/gh/etn-ccis/blui-doc-it/tree/master) +[![Build](https://github.com/etn-ccis/blui-doc-it/actions/workflows/blui-ci.yml/badge.svg?branch=master)](https://github.com/etn-ccis/blui-doc-it/actions/workflows/blui-ci.yml) Doc-It is the source code for [brightlayer-ui.github.io](brightlayer-ui.github.io), documentation site for Brightlayer UI. The site is built to both provide documentation on how to use the system, but also as an example of how to use it. The entire site is using using the Brightlayer UI design system - built with React+Redux, Material UI, and the Brightlayer UI component library. @@ -41,7 +41,7 @@ The folder structure of the application is segregated to keep the application an |── /__types__ // shared type definitions |── /databases // databases generated automatically for the search functionality |── /app - │ |── /api // api utilities for pulling data from npm, github, circleci + │ |── /api // api utilities for pulling data from npm, github │ |── /assets // images and icons │ |── /components // re-usable component definitions │ |── /hooks // react hook definitions diff --git a/cypress.json b/cypress.json deleted file mode 100644 index a56d1ac68..000000000 --- a/cypress.json +++ /dev/null @@ -1 +0,0 @@ -{ "video": false } diff --git a/cypress/fixtures/example.json b/cypress/fixtures/example.json deleted file mode 100644 index 519902d71..000000000 --- a/cypress/fixtures/example.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "Using fixtures to represent data", - "email": "hello@cypress.io", - "body": "Fixtures are a great way to mock data for responses to routes" -} diff --git a/cypress/plugins/index.js b/cypress/plugins/index.js deleted file mode 100644 index 9dca5dd78..000000000 --- a/cypress/plugins/index.js +++ /dev/null @@ -1,21 +0,0 @@ -/// -// *********************************************************** -// This example plugins/index.js can be used to load plugins -// -// You can change the location of this file or turn off loading -// the plugins file with the 'pluginsFile' configuration option. -// -// You can read more here: -// https://on.cypress.io/plugins-guide -// *********************************************************** - -// This function is called when a project is opened or re-opened (e.g. due to -// the project's config changing) - -/** - * @type {Cypress.PluginConfig} - */ -module.exports = (on, config) => { - // `on` is used to hook into various events Cypress emits - // `config` is the resolved Cypress config -}; diff --git a/cypress/support/README.md b/cypress/support/README.md deleted file mode 100644 index f32b385c6..000000000 --- a/cypress/support/README.md +++ /dev/null @@ -1,13 +0,0 @@ -Applitools admin console test results https://auth.applitools.com/users/login -Authentication located in Teams wiki Brightlayer UI Logistical. - -Cypress.io and Applitools eyes-cypress package are configured to run out of the integration folder. UI tests are defined by vs-test-name.spec.js and normal cypress tests are test-name.spec.js - -Currently we have 2 placeholder tests. - -- UI Test on landing page across 4 browsers as a baseline -- UI test on theme guide page - -``` -TODO: add dev/test details to run locally -``` diff --git a/cypress/support/commands.js b/cypress/support/commands.js deleted file mode 100644 index ca4d256f3..000000000 --- a/cypress/support/commands.js +++ /dev/null @@ -1,25 +0,0 @@ -// *********************************************** -// This example commands.js shows you how to -// create various custom commands and overwrite -// existing commands. -// -// For more comprehensive examples of custom -// commands please read more here: -// https://on.cypress.io/custom-commands -// *********************************************** -// -// -// -- This is a parent command -- -// Cypress.Commands.add("login", (email, password) => { ... }) -// -// -// -- This is a child command -- -// Cypress.Commands.add("drag", { prevSubject: 'element'}, (subject, options) => { ... }) -// -// -// -- This is a dual command -- -// Cypress.Commands.add("dismiss", { prevSubject: 'optional'}, (subject, options) => { ... }) -// -// -// -- This will overwrite an existing command -- -// Cypress.Commands.overwrite("visit", (originalFn, url, options) => { ... }) diff --git a/cypress/support/index.js b/cypress/support/index.js deleted file mode 100644 index 37a498fb5..000000000 --- a/cypress/support/index.js +++ /dev/null @@ -1,20 +0,0 @@ -// *********************************************************** -// This example support/index.js is processed and -// loaded automatically before your test files. -// -// This is a great place to put global configuration and -// behavior that modifies Cypress. -// -// You can change the location of this file or turn off -// automatically serving support files with the -// 'supportFile' configuration option. -// -// You can read more here: -// https://on.cypress.io/configuration -// *********************************************************** - -// Import commands.js using ES2015 syntax: -import './commands'; - -// Alternatively you can use CommonJS syntax: -// require('./commands') diff --git a/package.json b/package.json index 79db55f31..e2e796b52 100644 --- a/package.json +++ b/package.json @@ -50,9 +50,6 @@ "prettier": "prettier \"src/**/**.{ts,tsx,js,jsx,json,css,scss,html,md}\" --write", "prettier:check": "prettier \"src/**/**.{ts,tsx,js,jsx,json,css,scss,html,md}\" --check", "precommit": "yarn prettier && yarn lint && yarn check:links", - "cy:run": "cypress run", - "cypress:open": "cypress open", - "cytest": "start-server-and-test start http://localhost:3000 cy:run", "indexer": "cd __scripts__/crawl && node crawler.js && node indexer.js && cd ../.. && prettier \"src/database/*.json\" --write", "analyze": "source-map-explorer 'build/static/js/*.js'" }, @@ -80,11 +77,11 @@ "@craco/craco": "^7.1.0", "@mdx-js/loader": "^2.1.5", "@mdx-js/mdx": "^2.2.1", - "@mdx-js/react": "^2.1.5", + "@mdx-js/react": "^3.0.1", "@testing-library/jest-dom": "^5.16.5", "@testing-library/react": "^13.4.0", "@testing-library/user-event": "^14.4.3", - "@types/color": "^3.0.3", + "@types/color": "^3.0.6", "@types/jest": "^27.5.2", "@types/lodash.debounce": "^4.0.7", "@types/mdx": "^2.0.3", diff --git a/src/__configuration__/contributors/contributors.ts b/src/__configuration__/contributors/contributors.ts index c0f6ab9cf..489cd9f53 100644 --- a/src/__configuration__/contributors/contributors.ts +++ b/src/__configuration__/contributors/contributors.ts @@ -14,8 +14,8 @@ import JosephBoyle from '../../app/assets/credits/joseph-boyle.png'; import JoaoMota from '../../app/assets/credits/joao-mota.jpg'; import EvanMcLaughlin from '../../app/assets/credits/evan-mclaughlin.jpeg'; import RaghavC from '../../app/assets/credits/raghavendran-chithirarajan.jpeg'; -import YazadSidhwa from '../../app/assets/credits/yazad-sidhwa.jpg'; import ThomasDailey from '../../app/assets/credits/thomas-dailey.jpg'; +import PriyankaKM from '../../app/assets/credits/priyanka-km.jpeg'; import { OtherContributor } from '../../__types__'; @@ -138,8 +138,8 @@ export const contributors: OtherContributor[] = [ image: EvanMcLaughlin, }, { - name: 'Yazad Sidhwa', - role: 'Intern', - image: YazadSidhwa, + name: 'Priyanka KM', + role: `Front-End Developer`, + image: PriyankaKM, }, ]; diff --git a/src/__configuration__/contributors/currentMaintainers.ts b/src/__configuration__/contributors/currentMaintainers.ts index 3f9ff6b2e..140e0cdfb 100644 --- a/src/__configuration__/contributors/currentMaintainers.ts +++ b/src/__configuration__/contributors/currentMaintainers.ts @@ -6,6 +6,10 @@ import ManojLokesh from '../../app/assets/credits/manoj-lokesh.jpg'; import AubreyThompson from '../../app/assets/credits/aubrey-thompson.jpg'; import ArshdeepSingh from '../../app/assets/credits/arshdeep-singh.jpg'; import AndrewPuhalla from '../../app/assets/credits/andrew-puhalla.jpeg'; +import KomalRanjit from '../../app/assets/credits/komal-ranjit.jpg'; +import ShubhamVishwakarma from '../../app/assets/credits/shubham-vishwakarma.jpeg'; +import KomalDhere from '../../app/assets/credits/komal-dhere.jpg'; +import YazadSidhwa from '../../app/assets/credits/yazad-sidhwa.jpg'; import { CurrentMaintainter } from '../../__types__'; export const currentMaintainers: CurrentMaintainter[] = [ @@ -91,4 +95,44 @@ export const currentMaintainers: CurrentMaintainter[] = [ linkedIn: `https://www.linkedin.com/in/aubrey-thompson-02464391/`, }, }, + { + name: 'Komal Ranjit', + role: `Front-End Developer`, + image: KomalRanjit, + description: `Komal is a passionate front-end developer with experience in React.js and Appcelerator Titanium development. She is always eager to stay ahead in the dynamic world of tech and is dedicated to continuous learning and professional development. In her leisure time, she enjoys nature, with a love for gardening and swimming, finding them both as ways to recharge and relax.`, + contacts: { + github: `https://github.com/Komal-Ranjit`, + linkedIn: `https://www.linkedin.com/in/komal-ranjit-6a800718a/`, + }, + }, + { + name: 'Shubham Kumar Vishwakarma', + role: `Front-End Developer`, + image: ShubhamVishwakarma, + description: `Shubham is a front-end developer and has demonstrated his skills and ability in writing and maintaining clean reusable code. When Shubham is away from his workstation you will usually find him exploring the beauty of nature, our mother earth <3`, + contacts: { + github: `https://github.com/ShubhamProjects`, + linkedIn: `https://www.linkedin.com/in/shubham-vishwakarma-7252221a9`, + }, + }, + { + name: 'Yazad Sidhwa', + role: `Intern`, + image: YazadSidhwa, + description: `Yazad is currently pursuing his M.S. in Computer Science at the University of California, Irvine. When he's not working, you’ll find him shooting hoops on the basketball court or kicking a soccer ball around. He is also an avid hiker, exploring trails with friends and is a total nerd for sci-fi films. Plus, he’s a foodie who loves discovering new restaurants.`, + contacts: { + github: `https://github.com/yazadsidhwa-eaton`, + linkedIn: `https://www.linkedin.com/in/yazad-sidhwa`, + }, + }, + { + name: 'Komal Dhere', + role: `Front-End Developer`, + image: KomalDhere, + description: `Meet Komal, a dedicated front-end developer who values continuous learning and personal growth. When she is not immersed in coding, you will find her unwinding with her favorite TV shows, exploring new recipes in the kitchen, and pursuing her passion for dancing.`, + contacts: { + github: `https://github.com/KomalGDhere-eaton`, + linkedIn: `https://www.linkedin.com/in/komal-dhere-4a7735153/`, + }, + }, ]; diff --git a/src/__configuration__/roadmap/index.ts b/src/__configuration__/roadmap/index.ts index 31a93a8b6..2b3dec3a8 100644 --- a/src/__configuration__/roadmap/index.ts +++ b/src/__configuration__/roadmap/index.ts @@ -1,12 +1,17 @@ import { Quarter, Release } from '../../__types__'; -export const CURRENT_RELEASE: Release = 'R32'; +export const CURRENT_RELEASE: Release = 'R33'; export const AVAILABLE_RELEASES: Array<{ name: Release; year: number; quarter: Quarter; }> = [ + { + name: 'R33', + year: 2024, + quarter: 'Q3', + }, { name: 'R32', year: 2024, diff --git a/src/__types__/index.ts b/src/__types__/index.ts index 4fae7beab..194b9f79f 100644 --- a/src/__types__/index.ts +++ b/src/__types__/index.ts @@ -52,7 +52,8 @@ export type Release = | 'R29' | 'R30' | 'R31' - | 'R32'; + | 'R32' + | 'R33'; export type RoadmapItem = { name: string; diff --git a/src/app/api/index.tsx b/src/app/api/index.tsx index 9925d9208..a6210f518 100644 --- a/src/app/api/index.tsx +++ b/src/app/api/index.tsx @@ -9,10 +9,6 @@ export const github = axios.create({ Authorization: `token ${(process.env.REACT_APP_DOCIT_GITHUB_TOKEN || '').split('').reverse().join('')}`, }, }); -export const circleci = axios.create({ - baseURL: 'https://circleci.com/api/v1.1/project/github/etn-ccis/', - timeout: 5000, -}); export const npm = axios.create({ baseURL: 'https://api.npms.io/v2/', timeout: 5000, @@ -41,19 +37,20 @@ export const getBuildStatus = async (repository: string, branches: string[]): Pr let failed = 0; const results = []; for (const branch of branches) { - results.push( - circleci.get( - `blui-${repository}/tree/${branch.replace('-', '')}?limit=1&filter=completed&circle-token=${ - process.env.REACT_APP_DOCIT_CIRCLECI_TOKEN || '' - }` - ) - ); + results.push(github.get(`repos/etn-ccis/blui-${repository}/actions/runs?branch=${branch}`)); } const test = await Promise.all(results); for (let i = 0; i < test.length; i++) { const response = test[i]; - if (response && response.status === 200 && response.data[0].failed === false) { - failed += 0; + if (response && response.status === 200) { + const data = response.data.workflow_runs; + const buildjobs = data.filter((job: any) => job.name === 'Build'); + if (buildjobs.length > 0) { + const buildfailed = buildjobs[0].conclusion === 'failure'; + failed += buildfailed ? 1 : 0; + } else { + failed += 0; + } } else { failed += 1; } diff --git a/src/app/assets/credits/komal-dhere.jpg b/src/app/assets/credits/komal-dhere.jpg new file mode 100644 index 000000000..4bfc333b0 Binary files /dev/null and b/src/app/assets/credits/komal-dhere.jpg differ diff --git a/src/app/assets/credits/komal-ranjit.jpg b/src/app/assets/credits/komal-ranjit.jpg new file mode 100644 index 000000000..caa437a51 Binary files /dev/null and b/src/app/assets/credits/komal-ranjit.jpg differ diff --git a/src/app/assets/credits/priyanka-km.jpeg b/src/app/assets/credits/priyanka-km.jpeg new file mode 100644 index 000000000..5f44f31e4 Binary files /dev/null and b/src/app/assets/credits/priyanka-km.jpeg differ diff --git a/src/app/assets/credits/shubham-vishwakarma.jpeg b/src/app/assets/credits/shubham-vishwakarma.jpeg new file mode 100644 index 000000000..0f6154256 Binary files /dev/null and b/src/app/assets/credits/shubham-vishwakarma.jpeg differ diff --git a/src/app/components/resources/ButtonRow.tsx b/src/app/components/resources/ButtonRow.tsx index e5100e2cb..f81ab75c3 100644 --- a/src/app/components/resources/ButtonRow.tsx +++ b/src/app/components/resources/ButtonRow.tsx @@ -25,7 +25,10 @@ export const ButtonRow: React.FC = (props): JSX.Element => { const bugString = (bugLabels ? [...bugLabels, 'bug'] : ['bug']).map((label) => `+label%3A${label}`).join(''); const bugLink = `https://github.com/etn-ccis/blui-${repository}/issues?q=is%3Aissue+is%3Aopen${bugString}`; - const buildLink = `https://circleci.com/gh/etn-ccis/blui-${repository}${branch ? `/tree/${branch}` : ''}`; + // circleCI will need replaced with github + const buildLink = `https://github.com/etn-ccis/blui-${repository}/actions/workflows/blui-ci.yml${ + branch ? `?query=branch%3A${branch}` : '' + }`; const repoLink = `https://github.com/etn-ccis/blui-${repository}${branch ? `/tree/${branch}` : ''}/${workSpace}`; return ( diff --git a/src/database/sitemap-database.json b/src/database/sitemap-database.json index 44c3629cd..716967220 100644 --- a/src/database/sitemap-database.json +++ b/src/database/sitemap-database.json @@ -1 +1 @@ -{"":{"title":"Brightlayer UI | Powering Teams to Make What Matters*"},"/overview":{"title":"What is Brightlayer UI?","text":"import React from 'react';\nimport { Divider, ImageGrid } from '../app/components';\nimport DesignSystemImage from '../app/assets/design-system.jpg';\n\n{/* KEYWORDS: overview Brightlayer UI design development introduction */}\n\n# Welcome to Brightlayer UI\n\n\n\nBrightlayer UI is a complete design system for web and mobile applications. This system will help your team build beautiful applications that adhere to our design guidelines while ensuring flexibility and code reusability.\n\n> Check out our [Release Notes](/release-notes) to see what's new in the latest version of Brightlayer UI.\n\n## Design\n\nThe goal of the Brightlayer UI design system is to ensure consistency between software products delivered by different teams. With a common aesthetic and common guidelines, we can be sure that all products feel like they belong to the same family.\n\nBrightlayer UI is based on the [Material Design](https://m2.material.io/) language. If you are working with our Studio Blue design team, their designs will follow this standard. If you are not utilizing Studio Blue, ensure that your designers are following the Material Guidelines as well as any additional Brightlayer UI [design patterns](/patterns).\n\n## Development\n\nBrightlayer UI is also a development platform. This platform is intended to help development teams work quickly and efficiently by providing recommendations for technologies, tools/libraries, approaches to common challenges, as well as re-usable components. We support a variety of technologies to give your team the flexibility to choose what will work best for you.\n\n- To learn about the technologies we support, check out our [Web](/development/frameworks-web/intro) or [Mobile](/development/frameworks-mobile/intro) technology pages.\n- To learn about the different resources provided by Brightlayer UI, see our [Resources](/resources/developer) page.\n\n\n\n# About this site\n\nThis site will provide you with everything you need to get started with Brightlayer UI:\n\n- Information Guides, including information on starting a [New Project](/get-started/new-project) and the different types of applications you can build\n- Development Guides, including how to set up a [Development Environment](/development/environment), how to start a new project in any of our supported technologies, and what tools to use for [Testing](/development/testing)\n- [Design Guides](/design/intro) explaining how to use Brightlayer UI as a designer\n- Code Examples/[Design Patterns](/patterns) for how to build common elements of a Brightlayer UI application\n- An extensive set of [icons](/style/icon-library), [colors](/style/color), and [typography](/style/typography) guidelines that you can use in your designs\n- A [resources](/resources) page with links to all of the Brightlayer UI [NPM packages](https://www.npmjs.com/org/brightlayer-ui) and [GitHub repositories](https://github.com/etn-ccis?q=blui)\n- A community section with information on [reporting bugs](/community/bugs), [requesting features](/community/features), and more.\n"},"/get-started/new-project":{"title":"Where to Begin?","text":"import React from 'react';\nimport { Divider } from '../../app/components';\n\n{/* KEYWORDS: web mobile new project compare comparison */}\n\n# New Project Guide\n\nWhen approaching a potential new project, it can be challenging to know where to start. As a first step, it's helpful to decide if this is going to be a web application, mobile application, or both. Here is a run-down of these different types of applications.\n\n## Web Applications\n\nThese applications are accessible over the web. They can be accessed from any device with a network connection and a web browser (personal computer, mobile phone). To learn more about what a web application entails, check out our [Web App](/get-started/web) guide.\n\n## Mobile Applications\n\nMobile applications are intended to be used strictly on mobile devices (e.g., cell phones, tablets, etc.). These can be downloaded directly to the device (e.g., from the App Store or Google Play) and do not have to be connected to the Internet to run. To learn more about what a mobile application entails, including the difference between native and hybrid apps, check out our [Mobile App](/get-started/mobile) guide.\n\n\n\n# Deciding What Kind of Application to Build\n\nWith a new project, the nature of the project often determines which type of application you will need.\n\n## This Project is Replacing an Existing Product\n\nThink about the existing product and how it is used. Gather feedback from existing users and identify areas for improvement.\n\nIn general, you will want to at least provide the same type of application as before (unless user feedback suggests that it's not what they need). If you had a web application before, you may want to build a responsive web application this time. Alternatively, you may want to expand on the existing product by offering a mobile application.\n\n## This is a Brand New Product (never before seen)\n\nThink about how the product will be used. Does it offer features that users will want to access on the go? Is it going to be actively used in the field, or is it something users will more likely use from their desk?\n\nIn general, you can't go wrong with a web application. If you do your due diligence and design a properly responsive application, you will be able to access it from any connected device, including mobile. If you suspect that the primary mode of interacting with the application will be from a mobile device or if the application needs to work offline, you may want to consider building a dedicated mobile app.\n"},"/get-started/web":{"title":"Web Apps","text":"import React from 'react';\n\n{/* KEYWORDS: web application introduction framework */}\n\n# Web Applications\n\nWeb applications are everywhere. As the name suggests, they can be accessed from any device that can access the Internet. This means they have a lot of flexibility, but that comes with extra responsibility when you design them.\n\n## Responsive Design\n\nResponsive web design is critical for web applications today. With a nearly infinite variety of web-capable devices available, you'll want your application to look great on all of them. It's much easier to design a responsive web application if you start with mobile designs first. If you can fit your features into a mobile-sized display, it's much easier to scale up to a desktop size than it is to design for desktop and then scale everything down to mobile.\n\n## Get Started With a Web App\n\nThere are a lot of wonderful web applications out there and tons of options for how to proceed. Most modern applications are built with HTML / CSS and sit inside a JavaScript framework. If your application needs to be very small, or if you don't really have a need for a JavaScript infrastructure, you can certainly build static applications with just HTML and CSS. You can also use \"vanilla\" JavaScript without the need for including an entire JavaScript framework in your application. We support both Angular and React in the Brightlayer UI design system.\n\nFor a comparison of the pros / cons of each of these frameworks, see our [Framework Introduction](/development/frameworks-web/intro).\n\nOne of the goals of Brightlayer UI is to maximize maintainability and code re-use by standardizing on certain technologies. If you want to use a different framework from those that we support, you'll need to consider the trade-offs.\n"},"/get-started/mobile":{"title":"Mobile Apps","text":"import React from 'react';\nimport { Divider } from '../../app/components';\n\n{/* KEYWORDS: mobile hybrid compare comparison native application */}\n\n# Mobile Applications\n\nMobile applications are very popular. They can be accessed anywhere you can take your mobile device, both online and offline, and can take greater advantage of device features and capabilities than a web application.\n\nMobile applications come in two primary varieties: native apps and hybrid apps.\n\n## Native mobile apps\n\n- Must be built using the native code that runs on mobile devices. In general, that means Java (Android) or Swift / Objective C (iOS)\n- Should adhere to the design and development guidelines for the intended platforms:\n - [iOS Guidelines](https://developer.apple.com/design/human-interface-guidelines/designing-for-ios)\n {/* */}\n - [Android Guidelines](https://developer.android.com/design)\n {/* */}\n\nAndroid and iOS are the dominant players in the mobile market, but you should check with your particular users to see what is most prevalent in your target market.\n\n## Hybrid mobile apps\n\n- Maintained as a single code base that is deployed to multiple different device types (namely iOS and Android)\n- Built using web-technologies (i.e. JavaScript)\n - low barrier to entry for web developers\n- Implemented differently depending on the framework:\n - some compile down to native components\n - others render all content in a web view (essentially a web page running inside of an app)\n\n\n\n# Comparing the two approaches\n\n## Native mobile apps\n\n- Guaranteed to look & feel like an app since it uses native components\n- Requires more specialized development expertise\n- Requires separate code bases for different operating systems\n - Longer development time\n - More expensive / more maintenance\n\n## Hybrid mobile apps\n\n- Reduces development time thanks to shared code base\n- Provides more technology options\n - Many different hybrid platforms / tools available\n- Allows for a consistent look on different platforms\n- Makes development easier by using web technologies, but it's also easier to make something that doesn't follow standard mobile patterns\n\n\n\n# So, which one should you use?\n\nOur recommendation for mobile applications is to take a hybrid approach. This will allow you to deploy multiple versions of your application (i.e. iOS and Android) from a single code base. We offer support for several different approaches to building hybrid apps (see our [Mobile Framework Introduction](/development/frameworks-mobile/intro) to learn about the technologies we support).\n\n> **NOTE:** Brightlayer UI support for native mobile applications is limited - if you are planning to go this route, please [Contact us](/community/contactus).\n"},"/development/environment":{"title":"Environment Setup","text":"import React from 'react';\nimport { Divider } from '../../app/components';\n\n{/* KEYWORDS: developer develop environment guide tutorial */}\n\n# Setting up Your Development Environment\n\nGetting started is often the most frustrating part of application development. Fortunately, many of the modern JavaScript frameworks have made great strides in providing tools to get you up and running as quickly as possible. Below, we walk through the basics of getting your system set up to develop.\n\n## Integrated Development Environment (IDE)\n\nThere are a bunch of different IDEs on the market, and in general you should be able to use any of these that you like and are comfortable with. If you don't have a personal preference, we recommend trying [Visual Studio Code](https://code.visualstudio.com) - it is quite excellent and comes with a variety of tools to make your development experience seamless. And it's free!\n\n## Git\n\nChances are, you probably want to keep your application in source control. Git is one of the big players in this space (it's also the backbone for BitBucket).\n\nYou may already have git installed. To check, run:\n\n```sh\ngit --version\n```\n\nin a command prompt. If you don't have git installed, you can download it from the [Git Website](http://git-scm.com/downloads).\n\nIf you are behind a proxy, you'll also need to set up the git proxies as well:\n\n```sh\ngit config --global http.proxy http://url.to.your.proxy:port\ngit config --global https.proxy http://url.to.your.proxy:port\n```\n\nThe proxy addresses may vary depending on your location. Consult your local IT department if you’re not sure.\n\n## Node\n\nThe majority of JavaScript frameworks (and Brightlayer UI resources) are available via the Node Package Manager (NPM). This package manager allows you to install a variety of third party tools, packages, and other dependencies that you need for your applications. To use NPM, you will need to install [NodeJS](https://nodejs.org/en/download/).\n\n## Yarn\n\nOur projects and example code are set up to be run using yarn, but if you prefer, you're welcome to use NPM in your projects instead. Instructions for installing yarn on various operating systems can be found on the [Yarn Website](https://yarnpkg.com/en/docs/install).\n\nTo check if you have yarn installed, run:\n\n```sh\nyarn -v\n```\n\nfrom a command prompt. If you are behind a proxy, you will also need to configure your proxy settings. It may be sufficient for you to set `HTTP_PROXY` and `HTTPS_PROXY` in your environment variables. However, you may need to also explicitly set proxy values for yarn:\n\n```sh\nyarn config set proxy http://url.to.your.proxy:port\nyarn config set https-proxy http://url.to.your.proxy:port\n```\n\nThe proxy addresses may vary depending on your location. Consult your local IT department if you’re not sure. Once you have configured the proxy, you should be able to install packages by using:\n\n```sh\nyarn add \n```\n\n> If you are installing packages globally using yarn, you will need to ensure that your PATH variable has an entry pointing to your global yarn install directory. This location will vary based on your operating system.\n\n\n\n# Hybrid App Development\n\nIf you are setting up for building a mobile app, there are some additional steps you will want to take to prepare. The following requirements are the basics. Depending on your selected [framework](/development/frameworks-mobile/intro), there will be other specific setup steps detailed in our Getting Started Guides.\n\n## Prerequisites\n\n### Hardware\n\nMobile development is resource-intensive, so you will need a development machine that is up to the task. Your machine should at least match the following minimum requirements:\n\n- a Mac (if you plan on building or testing iOS locally)\n- 16GB RAM or more (running multiple emulators can easily push you over 20GB)\n- Solid State Hard Drive (SSD)\n- 5/6 Gen Core i7 with Virtualization Technology or better\n\n### Software\n\nThere are a few software tools that you will need before you can get started:\n\n{/* */}\n\n- [Android Studio](https://developer.android.com/studio/) (required for building for Android)\n {/* */}\n- [xCode](https://developer.apple.com/xcode/) (Mac-only, required for building for iOS)\n"},"/development/cli":{"title":"Brightlayer UI CLI","text":"import React from 'react';\nimport { Divider, EmbeddedYouTubePlayer } from '../../app/components';\n\n{/* KEYWORDS: cli command line interface new project start */}\n\n# Brightlayer UI CLI\n\n\n\nThe Brightlayer UI CLI (Command-Line Interface) is a tool for quickly starting new projects using Brightlayer UI. It will create a skeleton project in your chosen framework and automatically integrate:\n\n- Material and Brightlayer UI component libraries\n- Brightlayer UI themes\n- Open Sans Typography package\n- Brightlayer UI colors package\n- Brightlayer UI code formatting and linting profiles (optional)\n\nWhen starting a new project, you will have the opportunity to select a template as your starting point, including a blank template, basic routing template, and a full authentication template.\n\n> These templates are available for [Angular](https://github.com/etn-ccis/blui-angular-cli-templates/blob/master/README.md#angular-cli-templates), [React](https://github.com/etn-ccis/blui-react-cli-templates/blob/master/README.md#react-cli-templates), and [React-Native](https://github.com/etn-ccis/blui-react-native-cli-templates/blob/master/README.md#react-native-cli-templates).\n\nTo start a new project with the CLI:\n\n```sh\nnpx -p @brightlayer-ui/cli blui new\n```\n\nFor more detailed information and usage instructions, check out the [@brightlayer-ui/cli](https://www.npmjs.com/package/@brightlayer-ui/cli) package on NPM.\n\n## Supported Frameworks\n\nThe Brightlayer UI CLI works with all Brightlayer UI supported frameworks: Angular, React, and React Native.\n"},"/development/frameworks-web/intro":{"title":"Introduction","text":"import React from 'react';\nimport { Divider } from '../../../app/components';\n\n{/* KEYWORDS: introduction web framework compare comparison */}\n\n# Brightlayer UI Web Frameworks\n\nBrightlayer UI supports web application development using Angular and React. Both are open source JavaScript frameworks with large communities of support and both have open source component libraries implementing Material Design. The two are quite comparable and you would not go wrong by choosing either, but there are some notable differences outlined below.\n\n## Angular (with Angular Material)\n\n- A comprehensive framework, with a lot of built-in features and functionality\n- Written in TypeScript (superset of JavaScript with strong variable typing)\n- Structured way of organizing your entire application (if following the Angular CLI)\n- May be more accessible to developers with greater back-end or full-stack experience\n- Maintained by Google\n- Learn more on the [Angular website](https://angular.io/)\n\n## React (with MUI)\n\n- A UI library for building custom Web Components / Applications\n- Can be combined with additional libraries (e.g. Redux) to be a more comprehensive framework\n- Virtual DOM allows for fewer re-renders (i.e., faster UI updates)\n- May be more accessible to developers with greater experience with JavaScript and front-end development\n- Maintained by Facebook\n- Learn more on the [React website](https://reactjs.org/)\n\n\n\n# Which framework should I use?\n\nChoosing a framework is entirely up to you. They each have their own pros and cons, so you'll need to decide what is best for your application. In general, if you have developers who are very familiar with a particular framework, it might be worthwhile to use that framework to avoid any unnecessary learning curves associated with a new one. If you don't have development resources yet, you will probably want to conduct a more in-depth analysis of the available frameworks to decide what is most appropriate for your application. Feel free to reach out to us for assistance if needed.\n\nIf you choose to use one of these frameworks, have a look at our Guides for using them with Brightlayer UI:\n\n- [Angular Guide](/development/frameworks-web/angular)\n- [React Guide](/development/frameworks-web/react)\n"},"/development/frameworks-web/angular":{"title":"Angular Guide","text":"import React from 'react';\nimport { Divider } from '../../../app/components';\n\n{/* KEYWORDS: angular web framework guide tutorial */}\n\n# Getting Started with Angular\n\nThe following instructions will guide you through starting a new Brightlayer UI project using Angular. Alternatively, you can also start your project by downloading one of our code samples from [Github](https://github.com/etn-ccis?q=blui) (the Login or Navigation examples are good projects to start from).\n\n## Using the Brightlayer UI CLI\n\nThe fastest way to start a new Brightlayer UI project is to use the [Brightlayer UI CLI](/development/cli). The CLI will automatically create a starter project for you (using the [Angular CLI](http://cli.angular.io/)) with all of the necessary Brightlayer UI dependencies pre-configured. To start an Angular project:\n\n```sh\nnpx -p @brightlayer-ui/cli blui new angular\n```\n\nYou will be asked to provide a name for your project and whether or not you want to use the Brightlayer UI eslint and prettier configurations files.\n\nThe Brightlayer UI CLI will automatically include:\n\n- Angular Material Component Library ([@angular/material](https://www.npmjs.com/package/@angular/material))\n- Brightlayer UI Component Library ([@brightlayer-ui/angular-components](https://www.npmjs.com/package/@brightlayer-ui/angular-components))\n- Brightlayer UI Themes ([@brightlayer-ui/angular-themes](https://www.npmjs.com/package/@brightlayer-ui/angular-themes))\n- Brightlayer UI Icons ([@brightlayer-ui/icons](https://www.npmjs.com/package/@brightlayer-ui/icons))\n- Brightlayer UI Colors ([@brightlayer-ui/colors](https://www.npmjs.com/package/@brightlayer-ui/colors))\n- Open Sans web font ([@font-source/open-sans](https://www.npmjs.com/package/@fontsource/open-sans))\n- Brightlayer UI ESLint and Prettier configurations, if selected ([@brightlayer-ui/eslint-config](https://www.npmjs.com/package/@brightlayer-ui/eslint-config) / [@brightlayer-ui/prettier-config](https://www.npmjs.com/package/@brightlayer-ui/prettier-config))\n\nFor detailed usage instructions, refer to the [Brightlayer UI CLI documentation](https://www.npmjs.com/package/@brightlayer-ui/cli).\n\n## Using an Existing Project\n\nIf you have an existing project and would like to integrate Brightlayer UI, you can follow the manual integration instructions below. If you have not already started your project, we recommend that you scaffold your project with the Brightlayer UI CLI.\n\n\n\n# Manual Brightlayer UI Integration\n\nBefore taking the following steps, you'll want to make sure that you have an existing application. If you used the Brightlayer UI CLI to start your project, these steps have already been done for you automatically.\n\n## Including the Component Libraries\n\n### Angular Material\n\nAngular projects should make use of the [Angular Material](https://material.angular.io/) component library. Our Brightlayer UI themes are designed to work with these components.\n\n```sh\nnpm install --save @angular/material\n// or\nyarn add @angular/material\n```\n\nFor detailed documentation about the various components available in Angular Material, as well as sample code and API reference, refer to the [Angular Material Documentation](https://material.angular.io/components/).\n\n### Brightlayer UI Components\n\nAdditionally, we have a [supplemental library](/development/components) of components designed specifically for Brightlayer UI applications. If you wish to use these components, you can install them by running:\n\n```sh\nnpm install --save @brightlayer-ui/angular-components\n// or\nyarn add @brightlayer-ui/angular-components\n```\n\n## Adding Brightlayer UI Themes\n\nBy default, your application will be themed with the Google Material theme. To use the [Brightlayer UI theme](https://www.npmjs.com/package/@brightlayer-ui/angular-themes), first install it:\n\n```sh\nnpm install --save @brightlayer-ui/angular-themes\n// or\nyarn add @brightlayer-ui/angular-themes\n```\n\nInstalling the theme package will automatically include the Open Sans web font package as well as the Brightlayer UI [colors](https://www.npmjs.com/package/@brightlayer-ui/colors) package. In order to use the Brightlayer UI themes and font (Open Sans), you will need to modify your angular.json file \"styles\" entries (there is one under \"build\" and one under \"test\") to include the Brightlayer UI themes and Open Sans reference:\n\n```json\n\"styles\": [\n \"src/styles.scss\",\n \"./node_modules/@brightlayer-ui/angular-themes/theme.scss\",\n \"./node_modules/@brightlayer-ui/angular-themes/open-sans.scss\",\n],\n```\n\n### Applying the Theme\n\nYou can apply the theme to your application by adding the proper class to your application's body element:\n\n```html\n// Default Theme\n\n\n// Dark Theme\n\n```\n\n> If you do not specify a theme class, your application will use the default Material theme.\n\nYou can access the fonts using mat-typography, e.g.:\n\n```html\n
\n

H1 Text

\n

H2 Text

\n

Paragraph text

\n
Bold body copy
\n
\n```\n\nYou can access theme colors as well, e.g.:\n\n```html\nMy App\n```\n\nMore details about applying themes in your application can be found in [Theming your Angular Material app](https://material.angular.io/guide/theming).\n\n\n\n# Additional Information\n\n## Code Formatting / Style\n\nBrightlayer UI provides packages for code standards and style using ESLint and Prettier. These packages are used internally by the Brightlayer UI team, but they can also be used in your projects. You can find instructions for adding these packages to your project on [GitHub](https://github.com/etn-ccis/blui-code-standards).\n\n## Browser Support\n\nBrightlayer UI supports the same browsers as Angular and Angular Material. For specifics, please check out their support pages:\n\n- [Angular CLI](https://angular.io/guide/browser-support)\n- [Angular Material](https://github.com/angular/material2#browser-and-screen-reader-support)\n\n> With the end-of-life of Internet Explorer 11, Brightlayer UI will no longer be supporting IE11 as of 2021.\n\n## License Information\n\n[Angular](https://github.com/angular/angular/blob/master/LICENSE) and [Angular Material](https://github.com/angular/material2/blob/master/LICENSE) are both available under the MIT License.\n"},"/development/frameworks-web/react":{"title":"React Guide","text":"import React from 'react';\nimport { Divider } from '../../../app/components';\n\n{/* KEYWORDS: react web framework guide tutorial */}\n\n# Getting Started with React\n\nThe following instructions will guide you through starting a new Brightlayer UI project using React. Alternatively, you can also start your project by downloading one of our code samples from [Github](https://github.com/etn-ccis?q=blui) (the Login or Navigation examples are good projects to start from).\n\n## Using the Brightlayer UI CLI\n\nThe fastest way to start a new Brightlayer UI project is to use the [Brightlayer UI CLI](/development/cli). The CLI will automatically create a starter project for you (using [Create React App](https://github.com/facebookincubator/create-react-app)) with all of the necessary Brightlayer UI dependencies pre-configured. To start a React project:\n\n```sh\nnpx -p @brightlayer-ui/cli blui new react\n```\n\nYou will be asked to provide a name for your project and whether you want to use the Brightlayer UI eslint and prettier configuration files.\n\nThe Brightlayer UI CLI will automatically include:\n\n- MUI Component Library and Icons ([@mui/material](https://www.npmjs.com/package/@mui/material) / [@mui/icons-material](https://www.npmjs.com/package/@mui/icons-material))\n- Brightlayer UI Component Library ([@brightlayer-ui/react-components](https://www.npmjs.com/package/@brightlayer-ui/react-components))\n- Brightlayer UI Themes ([@brightlayer-ui/react-themes](https://www.npmjs.com/package/@brightlayer-ui/react-themes))\n- Brightlayer UI Icons ([@brightlayer-ui/icons-mui](https://www.npmjs.com/package/@brightlayer-ui/icons-mui))\n- Brightlayer UI Colors ([@brightlayer-ui/colors](https://www.npmjs.com/package/@brightlayer-ui/colors))\n- Open Sans web font ([@fontsource/open-sans](https://www.npmjs.com/package/@fontsource/open-sans))\n- Brightlayer UI ESLint and Prettier configurations, if selected ([@brightlayer-ui/eslint-config](https://www.npmjs.com/package/@brightlayer-ui/eslint-config) / [@brightlayer-ui/prettier-config](https://www.npmjs.com/package/@brightlayer-ui/prettier-config))\n- Enzyme testing library ([enzyme](https://www.npmjs.com/package/enzyme) / [enzyme-adapter-react-16](https://www.npmjs.com/package/enzyme-adapter-react-16))\n\nFor detailed usage instructions, refer to the [Brightlayer UI CLI documentation](https://www.npmjs.com/package/@brightlayer-ui/cli).\n\n## Using an Existing Project\n\nIf you have an existing project and would like to integrate Brightlayer UI, you can follow the manual integration instructions below. If you have not already started your project, we recommend that you scaffold your project with the Brightlayer UI CLI.\n\n\n\n# Manual Brightlayer UI Integration\n\nBefore taking the following steps, you'll want to make sure that you have an existing application. If you used the Brightlayer UI CLI to start your project, these steps have already been done for you automatically.\n\n## Including the Component Libraries\n\n### MUI\n\nReact projects should make use of the [MUI](https://mui.com/) component library, formerly known as Material UI. Our Brightlayer UI themes are designed to work with these components. You'll also want to install the icons.\n\n```sh\nnpm install --save @mui/material @mui/icons-material @emotion/react @emotion/styled\n// or\nyarn add @mui/material @mui/icons-material @emotion/react @emotion/styled\n```\n\nFor detailed documentation about the various components available in MUI, as well as sample code and API reference, refer to the [MUI Documentation](https://mui.com/).\n\n### Brightlayer UI Components\n\nAdditionally, we have a [supplemental library](/development/components) of components designed specifically for Brightlayer UI applications. If you wish to use these components, you can install them by running:\n\n```sh\nnpm install --save @brightlayer-ui/react-components\n// or\nyarn add @brightlayer-ui/react-components\n```\n\n## Adding Brightlayer UI Themes\n\nBy default, your application will be themed with the Google Material theme. To use the [Brightlayer UI theme](https://www.npmjs.com/package/@brightlayer-ui/react-themes), first install it:\n\n```sh\nnpm install --save @brightlayer-ui/react-themes\n// or\nyarn add @brightlayer-ui/react-themes\n```\n\nInstalling the theme package will automatically include the Open Sans web font package as well as the Brightlayer UI [colors](https://www.npmjs.com/package/@brightlayer-ui/colors) package.\n\n### Applying the Theme\n\nImport the theme files, MUI theme provider, and **Open Sans** font into your application, e.g. in App.js:\n\n```tsx\nimport { ThemeProvider, createTheme } from '@mui/material';\nimport CssBaseline from '@mui/material/CssBaseline';\nimport * as BLUIThemes from '@brightlayer-ui/react-themes';\nimport '@brightlayer-ui/react-themes/open-sans';\n```\n\nTo add the theme to your whole application, you would simply add a `` around your top-level component and pass it the theme you want to use, e.g.:\n\n```tsx\n\n \n \n\n```\n\nYou can read about [React Theming](https://mui.com/customization/theming/) to learn more.\n\n\n\n# Additional Information\n\n## Code Formatting / Style\n\nBrightlayer UI provides packages for code standards and style using ESLint and Prettier. These packages are used internally by the Brightlayer UI team, but they can also be used in your projects. You can find instructions for adding these packages to your project on [GitHub](https://github.com/etn-ccis/blui-code-standards).\n\n> NOTE: the ESLint package is only available for TypeScript projects.\n\n## Browser Support\n\nBrightlayer UI supports the same browsers as React and MUI. For specifics, please check out their support pages:\n\n- [React](https://facebook.github.io/create-react-app/docs/supported-browsers-features)\n- [MUI](https://mui.com/material-ui/getting-started/supported-platforms/)\n\n> With the end-of-life of Internet Explorer 11, Brightlayer UI will no longer be supporting IE11 as of 2021.\n\n## License Information\n\n[React](https://github.com/facebook/react/blob/master/LICENSE) and [MUI](https://github.com/mui-org/material-ui/blob/master/LICENSE) are both available under the MIT License.\n"},"/development/frameworks-mobile/intro":{"title":"Introduction","text":"import React from 'react';\nimport { Divider } from '../../../app/components';\n\n{/* KEYWORDS: mobile hybrid framework compare comparison */}\n\n# Brightlayer UI Mobile (Hybrid) Frameworks\n\nBrightlayer UI supports hybrid mobile application development using React Native. Some of the key considerations when using React Native are:\n\n- Renders native UI elements (not a WebView)\n- Can re-use application logic code (React)\n- Requires writing new code for UI (learning curve)\n- Does not use CSS for styling (learning curve)\n- Provides access to hardware functionality through various plugins / libraries\n- Has a large community of support\n- Learn more on the [React Native Website](https://facebook.github.io/react-native/)\n\n\n\n# Building your application\n\nFollow our [React Native](/development/frameworks-mobile/react-native) guide for information on developing using this framework. This guide will walk you through the process of developing your application and ultimately creating a final binary to distribute (either to your testers or your final customers).\n\n## Deploying your application\n\nOnce you have built your application into a distributable binary, there are two options for distributing it.\n\n### Visual Studio App Center (formerly HockeyApp)\n\nVisual Studio App Center gives you a way to test your app with users before you are ready for final distribution. This service allows you to upload app binaries and create lists of people with whom to share them. These people will be notified via email when new versions of the app are available, and they will be prompted to download and install them directly onto their devices. You will need to request access to Visual Studio App Center from IT.\n\n### App Store / Play Store\n\nFor the final distribution of your application, you will need to utilize App Store Connect and / or Google Play Console.\n\n# What about other mobile frameworks?\n\nThere is a wide variety of different technologies on the market for developing mobile apps, including native (Objective C / Swift, Kotlin / Java) and hybrid frameworks (Flutter, Ionic, Cordova, Xamarin, React Native, etc.).\n\nWe recommend and support development using React Native for these key reasons:\n\n- Maintaining a single code base that can deploy to iOS or Android saves time over building two separate native apps.\n- React Native gives a truer native experience than other \"web wrapper\" frameworks, which tend to present a clunkier user experience.\n- React Native has a well-supported open-source implementation of Material Design.\n- Business logic code can be shared with existing web applications built using React.\n- Supporting one framework allows us to concentrate our resources on building more features rather than having a smaller feature set across multiple technologies.\n- Encouraging teams to use the same technology stack maximizes the potential for code sharing between different teams.\n\nThere may be circumstances where a different technology makes more sense for your project. For example, if you have an existing web app built using Angular, you may not want to start from scratch and learn React in order to use React Native. In this case, you may be better off using a technology like Ionic to wrap your existing application in a wrapper for mobile.\n\nWhen selecting a technology for your project, you will need to weigh the pros and cons to determine which approach is best.\n\n\n"},"/development/frameworks-mobile/react-native":{"title":"React Native Guide","text":"import React from 'react';\nimport { Divider } from '../../../app/components';\n\n{/* KEYWORDS: react native mobile hybrid framework guide tutorial */}\n\n# Getting Started with React Native\n\nThe following instructions will guide you through setting up your computer for React Native development and starting a new Brightlayer UI project. Alternatively, you can start your project by downloading one of our code samples from [GitHub](https://github.com/etn-ccis?q=blui) (the Login example is a good project to start from) once you configure your environment.\n\n\n\n# Setting Up Your Environment\n\nYou'll need to start by following the general instructions for setting up your development environment for mobile found in our [Environment Guide](/development/environment).\n\n\n\n# Creating Your Application\n\n## Using the Brightlayer UI CLI\n\nThe fastest way to start a new Brightlayer UI project is to use the [Brightlayer UI CLI](/development/cli). The CLI will automatically create a starter project for you using the [React Native Community CLI](https://github.com/react-native-community/cli) with all of the necessary Brightlayer UI dependencies pre-configured. To start a React Native project:\n\n```sh\nnpx -p @brightlayer-ui/cli blui new react-native\n```\n\nYou will be asked to provide a name for your project and whether you want to use the Brightlayer UI eslint and prettier configurations files.\n\nThe Brightlayer UI CLI will automatically include:\n\n- React Native Paper Component Library ([react-native-paper](https://www.npmjs.com/package/react-native-paper))\n- Brightlayer UI Component Library ([@brightlayer-ui/react-native-components](https://www.npmjs.com/package/@brightlayer-ui/react-native-components))\n- Brightlayer UI Themes ([@brightlayer-ui/react-native-themes](https://www.npmjs.com/package/@brightlayer-ui/react-native-themes))\n- Material Icons ([react-native-vector-icons](https://www.npmjs.com/package/react-native-vector-icons))\n- Brightlayer UI Icons ([@brightlayer-ui/icons-svg](https://www.npmjs.com/package/@brightlayer-ui/icons-svg))\n- Brightlayer UI Colors ([@brightlayer-ui/colors](https://www.npmjs.com/package/@brightlayer-ui/colors))\n- Open Sans font\n- Brightlayer UI ESLint and Prettier configurations, if selected ([@brightlayer-ui/eslint-config](https://www.npmjs.com/package/@brightlayer-ui/eslint-config) / [@brightlayer-ui/prettier-config](https://www.npmjs.com/package/@brightlayer-ui/prettier-config))\n- Testing libraries ([jest](https://www.npmjs.com/package/jest) / [react-test-renderer](https://www.npmjs.com/package/react-test-renderer))\n\nFor detailed usage instructions, refer to the [Brightlayer UI CLI documentation](https://www.npmjs.com/package/@brightlayer-ui/cli).\n\n## Using an Existing Project\n\nIf you have an existing project and would like to integrate Brightlayer UI, you can follow the manual integration instructions below. If you have not already started your project, we recommend that you scaffold your project with the Brightlayer UI CLI.\n\n\n\n# Manual Brightlayer UI Integration\n\nBefore taking the following steps, you'll want to make sure that you have an existing application. If you used the Brightlayer UI CLI to start your project, these steps have already been done for you automatically.\n\n## Including the Component Libraries\n\n### Material Components\n\nReact Native projects should make use of the [React-Native-Paper](https://callstack.github.io/react-native-paper/) component library. Our Brightlayer UI themes are designed to work with these components. You'll also want to install [react-native-vector-icons](https://www.npmjs.com/package/react-native-vector-icons) to access the Material icons.\n\n```sh\nnpm install --save react-native-paper@4.0.0 react-native-vector-icons\n// or\nyarn add react-native-paper@4.0.0 react-native-vector-icons\n```\n\n> **NOTE**: react-native-paper@5.0.0 is currently available, however, we only support React Native Paper v4 at this time. Please be sure to keep peer-dependencies aligned as defined above to avoid potential conflicts.\n\n### Brightlayer UI Components\n\nWe have a [supplemental library](/development/components) of components designed specifically for Brightlayer UI applications. If you wish to use these components, you can install them by running:\n\n```sh\nnpm install --save @brightlayer-ui/react-components\n// or\nyarn add @brightlayer-ui/react-native-components\n```\n\n## Adding Brightlayer UI Themes\n\nIf you are using the recommended component libraries, your application will be themed with the Google Material theme by default. To use the Brightlayer UI theme, first install it:\n\n```sh\nnpm install --save @brightlayer-ui/react-native-themes\n// or\nyarn add @brightlayer-ui/react-native-themes\n```\n\n> Using the Brightlayer UI React Native theme **requires** that you add the Open Sans font to your application. You can learn how to do this by reading the instructions for [Vanilla React Native](https://medium.com/react-native-training/react-native-custom-fonts-ccc9aacf9e5e). You can find the fonts [here](https://github.com/etn-ccis/blui-react-native-cli-templates/tree/master/blank-typescript/fonts).\n\n## Applying the Theme\n\nImport the theme files and React Native Paper theme provider into your application, e.g. in App.js:\n\n```tsx\nimport { Provider as ThemeProvider } from 'react-native-paper';\nimport * as BLUIThemes from '@brightlayer-ui/react-native-themes';\n...\n\n \n\n```\n\nFor detailed information about theming, refer to the react-native-paper [theming guide](https://callstack.github.io/react-native-paper/docs/guides/theming).\n\n> NOTE: This theme only applies to the components in the react-native-paper and @brightlayer-ui/react-native-components package. It will not theme the components from other third party libraries. If you wish to use our theme to style your own components, refer to the react-native-paper [theming guide](https://callstack.github.io/react-native-paper/docs/guides/theming#extending-the-theme).\n\n### Avoiding Repeated Styles\n\nTo avoid adding repeatedly adding inline styles to standard components, you can define your own component that applies the styles and use that throughout your application, e.g.:\n\n```tsx\n// MyText.js\nexport default MyText = ({style, children, ...other}) => (\n \n {children}\n \n);\n\n// OtherFile.js\nimport Text from 'path/to/MyText.js';\n...\nThemed Text Object\n```\n\n\n\n# Writing a React Native Application\n\nIf you are familiar with React development, React Native will be relatively simple to understand. The application logic remains the same, while the UI requires a little adjustment. Rather than typical HTML elements, React Native UIs are built with a special library of [Components](https://facebook.github.io/react-native/docs/components-and-apis), including ``, ``, ``, etc. React Native layouts are built exclusively using FlexBox.\n\n## Running your application\n\nAfter you've created your application with a CLI, it can be run from the command line:\n\n```sh\ncd YourAppName\n\nnpm run \n// or\nyarn \n```\n\nWhen you make changes to the source code, the application will automatically rebuild and update on the device.\n\n> To run on an Android emulator, the emulator must already be running or you will see an error message, \"No connected devices found.\"\n\n> On a Mac, you may be prompted to install watchman (`brew install watchman`) or update a few settings to run the application.\n\n## Final Build\n\nNow, you can open the project folders in xCode (/ios/projectName.xcodeproj) or Android Studio (/android) and perform builds from the IDE. Depending on the version of React Native you are using, you may have to [manually bundle your JS code](https://stackoverflow.com/questions/44446523/unable-to-load-script-from-assets-index-android-bundle-on-windows) for Android.\n\n\n\n# Additional Information\n\n## Code Formatting / Style\n\nBrightlayer UI provides packages for code standards and style using ESLint and Prettier. These packages are used internally by the Brightlayer UI team, but they can also be used in your projects. You can find instructions for adding these packages to your project on [GitHub](https://github.com/etn-ccis/blui-code-standards).\n\n> NOTE: the ESLint package is only available for TypeScript projects.\n\n## Component recommendations\n\nThere are a lot of resources and components available on the market to help speed up your development and improve reusability. React Native also comes with a built-in component library. We recommend the following:\n\n- Navigation\n - [React Navigation](https://reactnavigation.org/) (JS-only implementation)\n - [React Native Navigation](https://wix.github.io/react-native-navigation/#/) (native implementation)\n- Component Libraries\n - [React Native Built-in Components](https://reactnative.dev/docs/components-and-apis)\n - [React Native Paper](https://callstack.github.io/react-native-paper/)\n - [React Native Elements](https://react-native-training.github.io/react-native-elements/)\n\n## License Information\n\n[React Native](https://github.com/facebook/react-native/blob/main/LICENSE-docs) is available under the MIT License.\n"},"/development/testing":{"title":"Testing","text":"import React from 'react';\nimport { DemoCard, ImageGrid, MaterialDesignDescription, Divider } from '../../app/components';\n\n# Testing Your Brightlayer UI Applications\n\n{/* KEYWORDS: testing test unit e2e tdd bdd integration cypress */}\n\nTesting is a critical component of successfully building and releasing an application. Despite the value and importance of testing, it is common for teams to overlook or neglect it. Testing should be considered from the very beginning of development, not as an afterthought once development is complete. In general, every time you write a new piece of code or update existing code, you should also write a test that verifies that your code is correct.\n\nThere are many [varieties of tests](https://www.atlassian.com/continuous-delivery/software-testing/types-of-software-testing), each with their own intended purpose. The most common types of tests are:\n\n- **Unit Tests**: verify individual methods, functions, or components.\n- **Integration Tests**: verify that different modules or services in your application work together.\n- **Functional Tests**: verify the output of certain actions based on business requirements.\n- **End-to-end (E2E) Tests**: verify that user behaviors / workflows function as expected.\n- **Acceptance Tests**: verify that the entire system meets the business requirements.\n- **Performance Tests**: verify that the system behaves correctly under heavy load.\n- **Smoke Tests: quick**: basic checks of the major features of the application.\n\nThis document focuses mainly on Unit Tests and E2E tests, as they are the easiest to automate.\n\n\n\n# Unit Tests\n\nUnit tests target the smallest pieces of your application (such as verifying inputs and outputs of a class method or function). These will likely make up the bulk of your tests because they are quick to write, easy to automate, and can help you achieve significant code coverage.\n\n> Code Coverage measures the percentage of your code that is verified by your tests.\n\nA unit test shouldn't have any external dependencies, such as other methods or APIs. By keeping unit tests isolated in this manner, it's easy to identify the cause of a failing test and implement a fix quickly. When you start combining features and methods together, you move into the realm of _integration testing_.\n\n## When to Write\n\nAs long as you are writing tests and achieving acceptable levels of coverage, the _when_ is not as important.\n\nSome teams elect to follow a Test-Driven Development (TDD) methodology, where unit tests are written prior to any code. In this situation the tests actually define the desired implementation of the application and the code is written to satisfy the tests.\n\nBehavior-Driven Development (BDD) is similar to TDD in that test cases are written prior to writing any applications code. However, these test cases focus more on the desired behavior (inputs and outputs) of the application, and less on the actual implementation. These are usually written in plain language rather than code.\n\nThe most important thing to keep in mind about tests is that they should provide confidence that the code and design are working as intended without issues in any scenario. For most teams, it's fine to write tests after features and functions are developed, so long as you write quality tests and achieve good coverage.\n\n## How to Write\n\nWhen unit testing components, the most effective tests are based on what is actually rendered on the screen rather than the internal implementation logic. The test should consider the application from the user's perspective and test things the user views and interacts with.\n\nFor example, consider testing an Open Button that should open a modal dialog when clicked. Your test should check that a button with the _Open_ label is rendered on the screen, and when it is clicked, the dialog is rendered on the screen with the correct content. You may be tempted to identify the button by a class or id, or test that a particular function is called when the button is pressed - these tests are not as effective because they are more likely to break if the implementation of the component changes, even though the end behavior is the same.\n\n- Test what the user sees (i.e., rendered output) and what the user can do  (i.e., interactions).\n- If there is visual change after an interaction, test for it.\n- If there is a value returned after an action, test for it.\n\n## Testing Frameworks\n\nAngular, React, and React Native all come with built-in unit testing frameworks.\n\n### Angular\n\nThe Angular CLI comes pre-configured with [Jasmine](https://jasmine.github.io/pages/getting_started.html) and [Karma](https://karma-runner.github.io/latest/index.html) for unit testing. When you create a new project, sample tests are created in your project for you (test files are identified by the `.spec.ts` file extension). You can execute the tests by running the following in your terminal:\n\n```sh\ncd your/project/root\nng test\n```\n\nThis will build your app and launch the browser with the test runner.\n\n### React\n\nThe Create React App CLI is pre-configured with the [Jest](https://github.com/facebook/jest) testing framework. When creating a new project, a sample test is created in your project for you (test files are identified by the `.test.js` or `test.ts` file extension). You can execute the tests by running the following in your terminal:\n\n```sh\ncd your/project/root\nnpm run test\n// or\nyarn test\n```\n\nThis will run your tests and show the pass / fail output in the terminal.\n\nThere are additional test utilities that complement Jest well. [Create React App](https://facebook.github.io/create-react-app/docs/running-tests) provides access to [React Testing Library](https://www.npmjs.com/package/@testing-library/react) through the `react-dom` dependency. The Brightlayer UI team has also made use of [Enzyme](https://airbnb.io/enzyme/), a testing framework created by AirBnB, and [Test Renderer](https://reactjs.org/docs/test-renderer.html).\n\n### React Native\n\nLike React, the React Native CLI also bundles Jest into your application. Most of the testing strategies and libraries can be shared between the two frameworks. You can also consider additional libraries like [React Native Testing Library](https://www.npmjs.com/package/@testing-library/react-native).\n\n\n\n# End-to-End Testing\n\nEnd-to-end tests at a step above unit tests, both in terms of complexity and what they test. They focus primarily on the flow of the application, making sure that a user's journey through the application has the expected outcomes. These tests can generally be categorized as:\n\n- **Acceptance Tests**: verify that various features and flows meet the customer expectations.\n- **Regression Tests**: verify that existing functionality is not broken when new features are added.\n\nThey should cover user stories that span multiple components and views, such as signing up for an accounts, logging in and out of the application, updating a profile, etc. These tests are not concerned with the underlying state or implementation of the application - just the end results.\n\nEnd-to-end tests usually run in a browser against a live system (in the case of web, using a test runner that automates the browser). Automated E2E tests can take a long time to run because of all of the different pieces involved and the scope of the tests. You should try to optimize your testing pipeline to run tests in parallel to finish faster.\n\nFunctional tests alone will not give you enough test coverage to avoid regressions. Unit tests aim to provide code coverage depth, while functional tests provide coverage over the breadth of user test scenarios.\n\n## How to Write\n\nEnd-to-end tests rely on the ability to find elements on the screen and interact with them in an automated way. This means that you need a reliable mechanism for selecting elements. Depending on your testing framework, there are different ways to select elements, including:\n\n- **CSS Selectors**: find elements by using CSS classes or rules (e.g., `.your-class-name`)\n- **Element Selectors**: find elements inside the elements (e.g., `#\\@\\@blui-drawerlayout-content > div > header > div > button`)\n- **xPath Selectors**: find selector within xPath (e.g., `//*[@id=\"@@blui-drawerlayout-content\"]/div/header/div/button`)\n- **ID Selectors**: find attribute id within elements (e.g., `#login-button`)\n\n> You can read more about different selector strategies on [Selenium Dev](https://www.selenium.dev/documentation/webdriver/elements/locators/) and {/* */}[software testing help](https://www.softwaretestinghelp.com/using-selenium-xpath-and-other-locators-selenium-tutorial-5/){/* */}.\n\nEach of these methods has their own advantages and disadvantages. A common pain point in E2E test automation is that modern Javascript platforms are constantly changing, particularly in the open source community. Many of these frameworks automatically (and dynamically) generate IDs and classes for components resulting in a constantly moving target for automation tooling. Identifying elements by these values (i.e., using IDs, CSS, or xPath locators _without_ property attributes) makes your tests brittle because they are subject to change any time a new version comes out (or even any time the page is reloaded).\n\nOne way to combat this in your own applications is to use dedicated attributes for testing (e.g., `test-id` or `dev-id`). By adding this test-specific attribute to the element, identifying the correct underlying component should be safer. Because this attribute is test-specific and the application logic does not use it, it will be less likely to change throughout the product lifecycle. Combining this approach with other selectors is a common and reliable approach for element identification.\n\n```html\n{/* Component code */}\n\n\n{/* Selector to use in a test */} WebElement click = driver.findElement(By.id(\"login-button\"));\n```\n\n## Testing Frameworks\n\nThere are many tools available for configuring automated E2E tests. Some of the more popular tools include:\n\n- [Selenium](https://www.selenium.dev/documentation/en/)\n- [Cypress](https://docs.cypress.io/guides/overview/why-cypress.html#In-a-nutshell)\n- [WebDriverIO](https://webdriver.io/docs/gettingstarted.html)\n\n### Selenium\n\nSelenium is a popular automation testing suite which can be used to automate the desktop and mobile web browser interactions. You can write test code in any of the languages supported by Selenium.\n\nSelenium test suite has several test frameworks available and each one can be customized to your project needs.\n\nFor more information, check out the browserstack [selenium guide](https://www.browserstack.com/guide/selenium-framework) or the official [selenium documentation](https://github.com/SeleniumHQ/selenium).\n\nThere are also a number of [Selenium tutorials](https://www.guru99.com/selenium-tutorial.html) available online to help you get started.\n\n### Cypress\n\nCypress is a popular open source testing framework that boasts support for any modern JavaScript framework. It works well for E2E tests in both Angular and React applications and is easier to use than some of the more traditional tools, such as Selenium.\n\nFor a more detailed write-up on Cypress, check out the official [Cypress Documentation](https://docs.cypress.io/guides/getting-started/installing-cypress.html#System-requirements).\n\n### WebDriverIO\n\nWebdriverIO is a popular Javascript based test automation framework built on top of node.js. It is an open-source project developed for the automation testing community. WebdriverIO is extendible, compatible and feature-rich.\n\nFor more information, check out the official [Webdriver.io documentation](https://webdriver.io/) and their [getting started guide](https://webdriver.io/docs/gettingstarted.html).\n\n\n"},"/development/components":{"title":"Components","text":"import React from 'react';\nimport { ComponentCatalogGrids } from '../../app/components';\n\n{/* KEYWORDS: components typography icon storybook devdoc catalogue catalog */}\n\n# Brightlayer UI Components\n\nBrightlayer UI offers custom component libraries to simplify building your application by implementing common use cases in Brightlayer UI and eliminating the need for multiple teams to build their own components. These components are supplementary to basic components offered by [Angular Material](https://material.angular.io/components/categories), [MUI](https://mui.com/material-ui/getting-started/supported-components/) and [React Native Paper](https://callstack.github.io/react-native-paper/).\n\nAll Brightlayer UI components are available as NPM packages:\n\n- [@brightlayer-ui/angular-components](https://www.npmjs.com/package/@brightlayer-ui/angular-components)\n- [@brightlayer-ui/react-components](https://www.npmjs.com/package/@brightlayer-ui/react-components)\n- [@brightlayer-ui/react-native-components](https://www.npmjs.com/package/@brightlayer-ui/react-native-components)\n\n\n"},"/design/intro":{"title":"Introduction","text":"import React from 'react';\nimport { Divider, LinkGrid, InDocButton } from '../../app/components';\nimport { patternLinks } from '../../__configuration__/design';\n\n{/* KEYWORDS: design tutorial environment begin introduction */}\n\n# Designing with Brightlayer UI\n\nUsing the Brightlayer UI design system as a designer can greatly improve your efficiency and the quality of your products. Brightlayer UI has many patterns and guidelines (color usage, typography, iconography, etc.) to address the most common elements and interactions that you might encounter when designing a product. By following these recommendations and using pre-defined resources from Brightlayer UI, your time is free to focus on the elements that make your project unique. In general, we recommend trying to use Brightlayer UI for 80% of your product's needs.\n\n## We use Figma\n\nWe host and maintain all [our design assets](/resources/designer) through Figma. Figma is a powerful prototyping tool that facilitates collaboration and sharing of design assets between teams. It can be used on the web, and they also provide a desktop app for Mac and Windows. To use Figma, you will need to [sign up](https://www.figma.com/) for an account.\n\nIf this is the first time you've ever used Figma, consider going through {/* */}[one of its official tutorials](https://help.figma.com/hc/en-us/sections/4405269443991-Figma-for-Beginners-tutorial){/* */}. Or if you prefer video tutorials to follow through, websites such as [Pluralsight](https://www.pluralsight.com/courses/figma-getting-started) and even [YouTube](https://www.youtube.com/watch?v=g6rQFP9zCAM) have tutorials for beginners. If you come from another professional UI design tool like Sketch, Figma also [provides details on how to migrate](https://www.figma.com/best-practices/what-to-expect-when-moving-from-sketch-to-figma/).\n\n\n\n## Guidelines\n\nBrightlayer UI has design guidelines that serve as the foundation for the design system. These are intentional design choices we made to shape the Brightlayer UI brand — what Brightlayer UI applications should look like and how users should interact with them.\n\n\n\n\n\n# General Guidance\n\nThe best designs generally start with mobile first, and that's what we recommend as well when working with the Brightlayer UI design system. It's much easier to scale designs up than to scale them down. We also strongly encourage you to perform extensive user research to truly understand your users and their needs, skills, preferences, and tendencies.\n\n## Web Applications\n\nKeep the interface simple - avoid unnecessary elements and ensure the language used for labels and messaging is clear.\n\n{/* image */}\n\nStrive for consistency by using pre-defined Brightlayer UI UI elements where possible. By using these elements, your users will feel more familiar and will be able to get things done quickly. You can also help ensure consistency by defining patterns in language, layout, and design that are used throughout the application.\n\n{/* image */}\n\nBe purposeful when laying out page content. Consider space and the relationship between items on the page. Structure pages based on importance.\n\n{/* image */}\n\nUse the typography guidelines to create hierarchy and clarity. An effective type hierarchy increases scalability, legibility, and readability.\n\n{/* image */}\n\nEnsure that the application provides effective feedback to users. Make sure that you communicate location, actions, changes in state, and errors to users. Brightlayer UI has various UI elements to assist with communicating this information.\n\n{/* image */}\n\nConsider using defaults. If you have a strong understanding of the users of your application, careful planning around default states, actions, and paths can reduce the burden on your users.\n\n{/* image */}\n\n## Mobile Applications\n\nGenerally, interfaces less than seven inches in width should be treated as a mobile (phone) device. Font styles and layouts should be consistent across devices as much as possible - your product should feel like the same application regardless of the device used to access it. When working with a dedicated mobile app, familiarize yourself with device / platform capabilities and take advantage of these where possible.\n\n{/* image */}\n\nA fundamental principle for mobile design is to include only the information that is necessary. Don't overload the user with excessive information. Mobile devices are a convenient way to quickly consume information on the go and the information presented should reflect this.\n\n{/* image */}\n\nInterfaces greater than seven inches in width should be treated as a tablet device. As with phone devices, font styles and layouts should be consistent across devices in this class. However, you may find it appropriate to have some differences between phone and tablet devices because of the difference in screen real estate.\n\n{/* image */}\n\nTablet designs should look and feel like a desktop application / website, but they should function like a phone app.\n\n{/* image */}\n\nAs technology continues to evolve, it is important to consider scaling for the future. Products such as non-mobile touch screens, interactive displays, automotive displays, and touch screen laptops should be considered during your design phase.\n\n{/* image */}\n\n\n\n# Contributing\n\nWe encourage everyone to provide feedback, new design concepts, patterns, suggestions, or other ideas to help us create the most useful design system for our community. If you would like to contribute back, please [contact us](/community/contactus)!\n\nIn order to maintain the quality standards for Brightlayer UI resources, any submissions will be subject to review by the Brightlayer UI maintainers. If your design is made a part of Brightlayer UI, we'll add items onto our backlog to bring them to life in code for developers to use.\n"},"/design/for-non-designers":{"title":"Design Training For Non Designers","text":"import { ImageGrid, LockedBehindEatonFirewall } from '../../app/components';\nimport ByNonDesigners from '../../app/assets/design/by-non-designers.webp';\nimport ByDesigners from '../../app/assets/design/by-designers.webp';\n\n# Design Training for Non-designers\n\nDesign is a critical part of product development, and there’s no substitute for having a dedicated designer embedded with the product team. That said, every team member (including engineers and managers) can benefit from acquiring design skills. Improving your understanding of design principles will improve your ability to communicate with designers, ask thoughtful questions about designs, understand design intent, and more.\n\n\n\nListed below are some recommended design courses for non-designers. Most of these courses require a paid subscription, but the best content often does. These courses offer a much more robust learning experience compared to free materials / articles that you might find elsewhere.\n\n# User Experience Design\n\nUser experience (UX) design covers a broad spectrum of topics, from market research to design thinking. The key focus here is understanding the problem you are trying to solve and ensuring that you solve it in the right way. It is a critical skill for anyone on a front-end team, especially if you will be responsible for envisioning new concepts / features.\n\nThe UX training is better conducted in person with an experienced instructor. You may also rely on online resources to help you deepen your understanding of the domain.\n\n

\n Eaton Design Thinking Training\n \n

\n{/* */}\n- [Studio Blue Training Program - Design Thinking Resources]()\n{/* */}\n**LinkedIn Learning**\n\n- [User Experience (UX) for Non-Designers](https://www.linkedin.com/learning/user-experience-ux-for-non-designers)\n\n# User Interface Design\n\nUser interface (UI) design deals with the visual side of design — how will you best present a piece of information on the screen. It is a good skill to have for team members who may need to improvise or incorporate small features into an established UI.\n\n**LinkedIn Learning**\n\n- [UX Design for Developers](https://www.linkedin.com/learning/ux-design-for-developers)\n\n**Pluralsight**\n\n- [User Experience Tips and Tricks for Developers](https://www.pluralsight.com/courses/ux-tips-tricks-developers)\n- [Hacking the User Experience / UX for Developers](https://www.pluralsight.com/courses/hacking-user-experience)\n- [Creating User Experiences: Fundamental Design Principles](https://www.pluralsight.com/courses/cux-designprinciples)\n\n**Readings**\n\n- [Top 10 Front-end Design Principles for Developers](https://www.toptal.com/front-end/front-end-design-principles)\n- [UI/UX design fundamentals for the front end developers](https://medium.com/@hayavuk/ui-ux-design-fundamentals-for-the-front-end-developers-688ba43eaed4)\n"},"/design/anatomy":{"title":"Design System Anatomy","text":"import React from 'react';\nimport { Divider, ImageGrid, RegularWidth } from '../../app/components';\nimport CategoriesImg from '../../app/assets/resource-anatomy/resource-categories.png';\nimport PatternStatesImg from '../../app/assets/resource-anatomy/pattern-states.png';\n\n{/* KEYWORDS: design anatomy components pages patterns workflows atomic */}\n\n# Design System Anatomy\n\nThe building blocks of the Brightlayer UI design system are broken down into four levels of increasing complexity: elements, components, pages, and workflows. When communicating with other members of the Brightlayer UI community, you should strive to use this terminology to promote effective collaboration and understanding. This is applicable to designers, developers, product managers, etc.\n\n\n\n## Foundations\n\nThe foundations include the most basic visual elements on the page, such as [color](/style/color), [icons](/style/icon-guidelines), [typography](/style/typography), etc. These typically have no behavior or interaction on their own, but instead are used to communicate information to a user, establish a brand, or lay the foundations for the Brightlayer UI components, pages, and workflows.\n\n## Components\n\nComponents are the basic functional units of the UI. They are usually interactive through clicking, expanding, etc. Components can be as simple (such as buttons, tabs, sliders) or complex (such as [navigation drawers](/patterns/navigation)). Simpler components are often combined to form complex ones.\n\nMost of the simple components in Brightlayer UI are defined and built by Material Design and the component libraries that implement it. Brightlayer UI focuses on defining and building advanced components that are shared across Brightlayer UI applications.\n\n## Pages\n\nPages are the largest single unit in the Brightlayer UI design system. These are typically full-screen designs that specify how certain pages can look in an application. Foundation of these pages should stay the same while there may be some room for customizations. Examples of pages include \"login (empty fields)\" and \"create password (invalid)\".\n\n## Workflows\n\nWorkflows are a sequence of pages combined with rules surrounding how a user goes from one page to another. These usually represent a common path that a user is expected to take to complete various tasks. Workflows that are defined in Brightlayer UI are intended to be nearly identical between applications. Examples of very common workflows include the [login](/patterns/user-auth) experience and user registration / sign up.\n\n\n\n# Design Patterns\n\n\n \n\n\n[Design patterns](/patterns) are very common in Brightlayer UI. A design pattern is a common interaction or behavior that can exist at any level in the design system hierarchy described above. For example, we may have a design pattern for showing actions available on a list item or how to interact with individual settings on a settings page.\n\nBecause a design pattern centers around interactions, they typically include different states. A button can be normal, hovered, or pressed. Similarly, a login workflow can involve login with 2FA, Captcha, or simply a username and password.\n\nFor each state, Brightlayer UI tries to provide:\n\n- Guidelines: How it's used and in what context\n- Design Specifications: How it looks\n- Interactions: How it goes from one state to another\n- Code: How it can be implemented\n\n\n\n# Brightlayer UI and the Atomic Design System\n\nIf you are familiar with other design systems, such as the [Atomic Design System](https://bradfrost.com/blog/post/atomic-web-design/), you may recognize some concepts used here. Brightlayer UI's \"components\" parallel Atomic Design's atoms, molecules, and organisms. The idea of \"pages\" is the same in both systems, but Brightlayer UI also goes one level further in each direction (i.e., Foundations and Workflows) to define a project's user experience more comprehensively.\n"},"/design/accessibility":{"title":"Accessibility","text":"import React from 'react';\nimport { MaterialDesignDescription, Divider, ImageGrid } from '../../app/components';\nimport { Link as LinkIcon } from '@mui/icons-material';\nimport AccessibilityDesignImg from '../../app/assets/design/design-color.png';\nimport PerceivableDesignImg from '../../app/assets/design/design-perceivable.png';\nimport UnderstandableDesignImg from '../../app/assets/design/design-understandable.png';\n\n{/* KEYWORDS: accessibility design styles compliance w3c */}\n\n# Accessibility\n\nAccessibility for the web refers to designing your websites and applications so that individuals with disabilities are able to use them effectively. Disabilities can come in many forms including visual, physical, auditory, etc. It is important to design your applications to be accessible, both to reach as wide an audience as possible and for potential legal reasons. Making your application accessible improves the user experience for individuals without disabilities as well.\n\n> For international products it is important to research what level of compliance is required by law — accessibility requirements vary from one country to another.\n\nThe best practice guidelines used internationally for making websites accessible are the [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG20/) (WCAG) 2.0, released by the World Wide Web Consortium (W3C) in 2008.\n\n\n\n# Four Principles of Accessibility\n\nThere are four principles that lay the foundation necessary for anyone to access and use web content — Perceivable, Operable, Understandable, and Robust.\n\n## Perceivable\n\nInformation and user interface components must be presented to users in ways that they can perceive. For example, a button should look like a button and not be hidden behind an image or other hard-to-distinguish elements.\n\n\n\n## Operable\n\nOperable means that users must be able to perform the actions required to interact with interface elements. This means that all functionality should be available via the keyboard (including navigation), temporary content should be displayed long enough to be read by individuals with visual impairments, etc.\n\n## Understandable\n\nUsers must be able to consume information and interact with the application easily. This includes using appropriate language (avoiding abbreviations, writing at an appropriate reading level, etc.), making sure that interface elements behave in consistent and predictable ways, providing helpful error messages and instructions, etc.\n\nFor example, accompanying a button with a text label makes it more understandable if the meaning of the icon on its own is unclear.\n\n\n\n## Robust\n\nWeb content must be robust enough that it can be interpreted reliably by a wide variety of users, including those who rely on assistive technologies (e.g., screen readers, text-to-speech software, alternative pointing devices, etc.). As assistive technologies advance, your applications will need to account for these advances.\n\n\n\n# Color\n\n\n\nBrightlayer UI colors and components have been tested to meet minimum accessibility requirements. By using these default styles, you should be able to reduce the effort required for your product to pass accessibility tests.\n\nIf your project requires the use of additional styles or colors, you should adhere to the following guidelines:\n\n- Use Brightlayer UI colors in the 500+ range for white backgrounds.\n- Avoid using yellow, red, and orange for text (except for single-line error messages on forms)\n- Do not rely on colors for instructions (e.g., do not say \"Click the red button to close\")\n\nMost Brightlayer UI text elements use the Black 500 color, with some headlines using Blue 500. Button labels should use White 50 for dark background and Black 500 on light backgrounds. You can check the contrast ratio to determine which option provides greater contrast.\n\n\n }\n />\n }\n />\n }\n />\n\n\n## Checking Contrast\n\nLow contrast makes it difficult for all users to view your product, especially for individuals with visual impairments. You can test your contrast ratios using free [online tools](https://webaim.org/resources/contrastchecker/) and [Figma plugins](https://www.figma.com/community/plugin/732603254453395948/Stark).\n\n\n\n# Text\n\nIn addition to making sure that the colors used for text are accessible, you should also ensure that text can be made larger without affecting the content or function of the page. Users with visual impairments may need to increase the font size of applications in order to read more clearly.\n\nMost browsers offer a feature for you to change the default font size (larger or smaller). You should test your application across multiple sizes to make sure that everything still looks right and functions correctly.\n\nMost Brightlayer UI components are designed to accommodate bigger font sizes when required.\n\n\n\n# Images\n\nAny images in your application should be accompanied by a caption or other descriptive text, unless they are purely for decoration. Decorative images should show a brief description on hover. Images should always include an \"alt\" property so that they are accessible to users utilizing a screen-reader or other assistive technologies.\n\n- Images should include descriptive text/alt text in the markup/code.\n- Complex images should have more detailed descriptions near the image\n- Videos must provide visual access to the audio information through in-sync captioning\n\n\n\n# Testing Tools For Web\n\nThe tools used in the Trusted Tester Test Process (and ICT Testing Baseline) have been chosen based on several factors including ease of use, ease of teaching, and accuracy of results. They are also free to install and use.\n\n- [Accessible Name & Description Inspector](https://www.ssa.gov/accessibility/andi/help/install.html) (ANDI)\n- Color Contrast Analyzer for [Mac](https://github.com/ThePacielloGroup/CCA-OSX/releases/tag/2.4) and [Windows](https://github.com/ThePacielloGroup/CCA-Win/releases/tag/2.5.0) (CCA)\n"},"/design/websites":{"title":"Websites","text":"import React from 'react';\nimport { Divider, ImageGrid } from '../../app/components';\nimport ResponsiveDesignImg from '../../app/assets/design/responsive-design.png';\nimport WebsiteDesign from '../../app/assets/design/website-design.jpg';\nimport WebApp from '../../app/assets/design/webapp.jpg';\nimport Website from '../../app/assets/design/website.jpg';\nimport Grid from '../../app/assets/design/grids.png';\n\n{/* KEYWORDS: web website application app design marketing */}\n\n# Designing for Websites\n\nBrightlayer UI is a design system for digital _applications_. However, it can also be adapted for use in traditional web sites as well.\n\n\n\n## Websites vs. Applications\n\nThe line between websites and web applications is often blurry. In general, websites primarily provide information in a read-only format for the purposes of education, promotion, marketing, etc.\n\nA web application is typically more interactive and provides users the ability to affect the data in the application (e.g., adding items, deleting items, etc.). These applications are typically built to serve a particular use case or function that users need to perform frequently.\n\nWebsites:\n\n- Static content\n- Usually publicly accessible\n- Read-only visual & text content\n- Less interactive / functional compared to web applications\n\nApplications:\n\n- Dynamic content\n- Often incorporates user accounts / authentication\n- Users can manipulate data\n- More interactive / functional compared to a website\n\n\n\n\n# Principles of Website Design\n\nThere are several key principles for effective website design. Many of these principles can also be considered when designing a web application, with some notable differences called out below.\n\n## Beauty & Simplicity\n\nHow your website looks is important, but it's not the reason users are coming to your site — typically they are looking for some particular piece of information. However, users _will_ notice a bad design, so making sure your website is visually appealing is still crucial.\n\nKeeping your designs simple is a way to strike balance. You should avoid unnecessary design elements (i.e., don't design for the sake of design) — this will only serve to overwhelm users and make it more difficult for them to find what they are looking for. A clean and simple design helps the audience focus on the value of the brand and on your content. Often, users will associate a website design with the quality of a particular company or product.\n\n> Using whitespace liberally can help maintain a simplistic design and also improve readability.\n\n## Effective Navigation\n\nUsers are typically coming to your website to find information, so you should make your website as easy to navigate as possible to maximize their chance of finding what they need. User should be able to land on your site and immediately identify where they need to go.\n\n- Primary navigation should be simple and located at the top of every page\n- Include additional navigation or a site map in the footer of your website\n- Consider adding breadcrumbs so users can quickly see where they are.\n - If you use breadcrumbs, they should be used on every page.\n- Include a search functionality so users can quickly find what they are looking for\n- Limit the number of navigation options (e.g., tabs, breadcrumbs, menus, etc.) per page\n- Limit the nesting of information where possible.\n - Try to keep your website to no more than three levels deep (use a pyramid structure to organize your content).\n\n## Layout & Hierarchy\n\nWhere and how content is presented is a critical aspect of website design. You should arrange the elements on each page so that the user will naturally gravitate to the most important elements first. Your goal should be to facilitate users' actions in a way that feels intuitive, natural, and enjoyable. You can draw your users to certain elements on the page by utilizing a combination of position, size, and color.\n\nYour website should be designed on a [grid system](https://www.smashingmagazine.com/2017/12/building-better-ui-designs-layout-grids/) to help tie elements together and promote responsiveness for different sized screens.\n\n\n\n## Colors\n\nColor can be very powerful when it is used effectively. You should keep colors to a minimum to maximize the effect in the areas where they are used. We recommend using no more than five different colors in your website designs (ideally shades of blue, black, gray, and white from the Brightlayer UI [palette](/style/color)). For product catalogs or commerce sites, you should absolutely use the product's branding color(s) on your site.\n\nYou should focus your use of color on image backgrounds, highlight colors, etc.\n\n## Typography\n\nIn general, websites following the Brightlayer UI design language should use the Open Sans font. If you require an alternative, you should ensure that any font you use is highly legible at all sizes.\n\n- Avoid using script fonts\n- Minimize the use of colored text and make sure it contrasts with the background color.\n- Use no more than three different typefaces.\n- Use no more than three different font sizes.\n- Keep body copy and label font sizes at 12px or larger\n - Do not use any text smaller than 8px\n\nYou can read more about typography in the [Typography](/style/typography) guide.\n\n## Graphics\n\nGraphics are most powerful when used sparingly. Only use graphics if they help the user complete a specific task or if they showcase a specific product / situation. You can read more about graphics in our [Illustrations](/style/illustrations) guide.\n\n## Consistency\n\nThe overall look and feel of your site should be consistent across pages. Backgrounds, colors, typefaces and the tone of writing are all areas where consistency has a positive impact on usability.\n\nConsistency does not mean every page should look identical. Try to define different layouts for specific types of pages (e.g., landing page, information page, product page, etc.). Use these layouts consistently throughout your website.\n\nIn addition to visual consistency, it is also important to maintain a consistent tone throughout the website. Your content should be written using the same voice throughout the website. Content should be descriptive and straight to the point — keep technical jargon to a minimum.\n\n## Responsiveness\n\nYour website should be functional across a wide range of different devices, including desktop computers, mobile phones, and tablets. Nearly 50% of all web traffic comes from mobile and tablet devices, so you should strive to follow a [mobile-first](https://medium.com/@Vincentxia77/what-is-mobile-first-design-why-its-important-how-to-make-it-7d3cf2e29d00) design strategy. Brightlayer UI is working to develop website grid templates for traditional website design in Figma. You can refer to [Material designs Responsive layout](https://m2.material.io/design/layout/understanding-layout.html) grid for more detailed information.\n\n\n\n## Accessibility\n\nThe audience for a website can be even more diverse than for a web application. Your website should be accessible to all potential users. As with any Eaton digital product it is important to refer to the [Accessibility](/design/accessibility) guide for more detailed information. The main principles still apply to website design.\n\n## Conventions\n\nThere are a number of conventions that users have come to expect from websites. You should strive to follow these conventions when possible:\n\n- Placing the main navigation at the top left or on the side of the site\n- Placing a product logo at the top left of the site\n - The logo should be clickable and take the user back to the home page\n- Links and buttons should change color / appearance when hovered over\n- Ensuring image galleries / slideshows have buttons for users to manually rotate slides\n- Use shopping cart icons on a commerce site.\n - Include a badge that indicates the number of items in the cart.\n\n{/* # Key Differences vs. Web Application */}\n"},"/design/project-identity":{"title":"Project Identity","text":"import React from 'react';\nimport { Divider, ImageGrid, MaterialDesignDescription } from '../../app/components';\nimport PxblueSmallAltIcon from '@brightlayer-ui/icons-mui/PxblueSmallAlt';\nimport ConsumerIndustrial from '../../app/assets/design/project-identity/consumer-industrial.png';\nimport StyleChoice from '../../app/assets/design/project-identity/style-choice.png';\nimport IllustrationConsumer from '../../app/assets/design/project-identity/illustration-consumer.png';\nimport IllustrationIndustrial from '../../app/assets/design/project-identity/illustration-industrial.png';\nimport ImageAppBar from '../../app/assets/design/project-identity/image-app-bar.png';\nimport ImageDrawerRegular from '../../app/assets/design/project-identity/image-drawer-regular.png';\nimport ImageDrawerProfile from '../../app/assets/design/project-identity/image-drawer-profile.png';\nimport ImageScorecardHeader from '../../app/assets/design/project-identity/image-scorecard-header.png';\nimport ImageLogin from '../../app/assets/design/project-identity/image-login.png';\nimport ImageSuccess from '../../app/assets/design/project-identity/image-success.png';\nimport VariationButton from '../../app/assets/design/project-identity/variation-button.png';\nimport VariationTextField from '../../app/assets/design/project-identity/variation-text-field.png';\nimport VerbiageNeutral from '../../app/assets/design/project-identity/verbiage-neutral.png';\nimport VerbiageExcitement from '../../app/assets/design/project-identity/verbiage-excitement.png';\nimport ListColorCorrect from '../../app/assets/design/project-identity/list-color-correct.png';\nimport ListColorIncorrect from '../../app/assets/design/project-identity/list-color-incorrect.png';\n\n{/* KEYWORDS: design tutorial branding brand identity flexible flex */}\n\n# Project Identity and Design Flexibility\n\nBrightlayer UI provides a foundation for designing and developing applications in a way that makes them feel like they are a part of the same brand. However, the purpose of Brightlayer UI is not to make every application look the same.\n\nAs Brightlayer UI serves as a design system for a wide range of applications, some projects might demand unique design or branding elements to better suit their audience. There is a balance that you must strike among maintaining consistency between applications and establishing a unique brand for each product. Brightlayer UI provides some of the basic elements and patterns to help you build consistency, leaving you more time to focus on what makes your product unique.\n\n}\n minCardHeight={'unset'}\n/>\n\n## Brightlayer UI is Flexible\n\nBrightlayer UI is not intended to stifle your creativity, but rather to enable it. Brightlayer UI standardizes some of the basic elements of design in order to foster consistency between projects, which in turn allows you to spend more of your time and creativity on the parts of your project that make it unique.\n\nJust as we build on top of [Material Design](https://m2.material.io) principles, you too can build on top of Brightlayer UI principles to make your products better for your target audience. There are many opportunities in Brightlayer UI where you are free to make changes and tweaks.\n\n\n\n## Build a Local Design System\n\nWe expect that you will establish your own local design system for your project that extends Brightlayer UI and adds your own style / identity. Depending on your use case, your design system may need to be more flashy, visual, relaxed, friendly, etc. Depending on where your application will be used, you may also need to change aspects of the design system related to accessibility (such as larger buttons for touch-screens) or legal requirements in your target markets.\n\n\n\nWhile establishing your local product identity, remember that Brightlayer UI is here to help establish consistency. You do not want to customize so much that this is lost. Below, we go into details about some common areas of customization as well as some areas that should be avoided.\n\n## Common Things to Change\n\nThere are some areas where we strongly encourage you to make changes and establish your own brand identity.\n\nKeep in mind that once you've established a local design system, you must make sure that you apply it consistently everywhere. You should use it in your packaging, your website, your email templates, the application, etc.\n\n### Illustrations\n\n\n\n[Illustrations](/style/illustrations) are common for [websites](/design/websites) and other consumer-facing products. Different image styles can create different moods (e.g., friendly vs. professional) and set the tone for how users will use your application.\n\n### Images\n\nSimilar to illustrations, images are another way to make your applications and websites more user-friendly.\n\n\n\n### Icons\n\nBrightlayer UI primarily uses the baseline style of Material Design's icons (see [our icon guideline](/style/icon-guidelines)).\n\nHowever, we understand that the current iconography set may not cover every single use case or requirement for your product. In these situations, you are welcome to invent your own icons or leverage [Material Design's community icons](https://materialdesignicons.com/). Before going this route, make sure that you have thoroughly explored the available icons first and when creating new icons, ensure that they follow the [Material Design icon design guidelines](https://m2.material.io/design/iconography/system-icons.html#design-principles).\n\n### Component Variants\n\n\n\nMany components have style variations. These variations are all available for you to use, and it is up to you to decide which ones work best for your application. Some common variations include:\n\n- Outlined vs. Contained / Filled\n- Flat vs. Elevated\n- Square vs. Rounded Corner vs. Round\n\n### Verbiage\n\n\n\nThe actual text used in your application can change based on your intended tone. For websites, you may want to use more persuasive and appealing language to encourage the audience to buy or use your product. Inside an application, you may want to use a more serious tone, especially for applications that deal with potential safety concerns. Consumer-facing products in general carry a more cheerful tone.\n\n\n\n## Things You Should NEVER Change\n\nWhen it comes to Brightlayer UI, you have a great deal of design freedom, but there are a few things you should never change. Most of these are related to maintaining visual consistency and other conventions between applications.\n\n### Theme\n\nBrightlayer UI [offers two themes](/style/themes): Blue theme and Blue Dark theme. Ideally, an application should support both themes, but some applications might be more usable depending on the environment and context of the usage.\n\nYou are expected to stay close to those two themes. Both themes have been thoroughly researched to ensure they meet the standards for usability and accessibility.\n\n> One notable exception to this rule is if you are building products that will be white-labeled or sold under a different brand. In this case, you may find it beneficial to create your own custom themes that will better align with the brand.\n\n### Status Colors\n\n\n\nBrightlayer UI has strict guidelines around our [status color palette](/style/color). The status colors are used to indicate the status of certain items or devices. These should not be changed for any reason — users should be able to instantly know what these colors mean in any Brightlayer UI application. Further, the colors you are using to brand your application should not interfere with these colors.\n\nThe only situation where these may be changed is if there is an industry-specific convention that differs from the Brightlayer UI recommendations (e.g., green = circuit closed, red = circuit open for breakers). In these situations, you should follow the industry-specific convention.\n\n### Font Family\n\nBrightlayer UI [uses Open Sans and Noto Sans](/style/typography) for all applications. You are encouraged to adjust font [weight and size](/style/typography#customization) where necessary to establish a visual type hierarchy, but we strongly discourage the use of any fonts other than Open Sans and Noto Sans, particularly any [Serif fonts](https://en.wikipedia.org/wiki/Serif).\n\n### Design Patterns\n\nThroughout our [design patterns](/patterns), we provide examples of \"things not to do\" — these are typically identified by an image with a red underline. You should never use any of these expressly-forbidden patterns in your products. In all cases, we provide an example of the preferred approach.\n"},"/design/design-audit":{"title":"UI Design Audits","text":"import { ImageGrid, RuleTable, TOC } from '../../app/components';\nimport Banner from '../../app/assets/design/design-audit/banner.svg';\nimport ExplainArchitecture from '../../app/assets/design/design-audit/explain-architecture.png';\nimport ExplainJourney from '../../app/assets/design/design-audit/explain-journey.png';\nimport TopSeverity from '../../app/assets/design/design-audit/top-severity.png';\nimport HighSeverity from '../../app/assets/design/design-audit/high-severity.png';\nimport MediumSeverity from '../../app/assets/design/design-audit/medium-severity.png';\nimport LowSeverity from '../../app/assets/design/design-audit/low-severity.png';\nimport Feature from '../../app/assets/design/design-audit/feature.png';\nimport Slides from '../../app/assets/design/design-audit/ppt.svg';\nimport DoDont from '../../app/assets/design/design-audit/do-dont.svg';\nimport Educational1 from '../../app/assets/design/design-audit/educational-1.png';\nimport Educational2 from '../../app/assets/design/design-audit/educational-2.png';\n\n{/* */}\n\n# UI Design Audits\n\nA design audit is a great way to ensure that your user interface design meets Brightlayer UI's design standard and lines up with other Brightlayer UI-based applications.\n\n\n\nDesign audits examine not only cosmetic and branding elements, but also the overall usability of products — this is especially important when the team does not have a professional UI/UX designer on staff.\n\nWe recommend doing design audits incrementally, focusing on a few key workflows initially and gradually expanding to the rest of the application. We also encourage teams to work with their auditors to perform design audits periodically. We recommend frequent audits during the initial product release period and every time there's a major upgrade to the product's user interface design. Teams are expected to address most of the audit comments in between.\n\nDon't wait until a product is ready for release to request a design audit. The design audit itself may take several weeks, depending on the scope, and implementing the recommended changes could take months.\n\nThis page outlines the process for audit requesters (“teams”) and auditors and should serve as a guideline for how UI design audits work.\n\n\n\n# Prepare for an Audit\n\n## Update Packages\n\nBrightlayer UI sometimes makes style updates to components and themes through our NPM packages. Cosmetic issues such as Material component styling can be easily addressed by updating software packages to the latest versions. Therefore, when possible, teams are encouraged to update their Brightlayer UI packages and other major packages to the latest version prior to requesting an audit.\n\nPlease refer to our [developer resources page](/resources/developer) to learn about our latest package versions.\n\nWe discourage custom component styling that overrides the Brightlayer UI theme — these can cause problems when updating to newer versions. If the product team identifies any styling that should be included as part of the Brightlayer UI component theme, please [contact us](/community/contactus) or log an issue.\n\n## Read Through Our Website\n\nPlease read through our [style guides](/style) and [design pattern guidelines](/patterns). Many examples cited by these guidelines came from design audits we did in the past and are representative of common mistakes we observed across multiple projects. Team members may be able to identify low-hanging fruit during this self-audit and address these problems ahead of the full audit.\n\n## Address Comments from Previous Audits\n\nIf the team has received audit comments in the past, team members should address these audit comments first before requesting a new one. In case audit comments cannot be addressed due to time / technical constraints, the team should inform their auditors about this.\n\n# Request for a Design Audit\n\nIdeally, a design audit is conducted periodically by someone outside the product team. Team members may [request](/community/contactus) a design audit from the Brightlayer UI team.\n\n## Give a Demo\n\nTeam members are expected to walk their auditors through the application to help them understand the big picture. This includes all major workflows of the application.\n\n## Grant Auditors Direct Access\n\nWhenever possible, teams are encouraged to create a safe environment for the auditor to test the project directly. This is to help the auditor explore user interactions and different workflow branches.\n\n## Communicate with User Journey\n\nUser experience design is centered around users. Instead of talking about the technical nature of the infrastructure, teams should explain their product in terms of user journeys. Who will use the application? What do they care about the most? How will the application solve this user’s problem?\n\n\n\n## Communicate the Limitations\n\nThe team should mention to its auditor any legacy issues (e.g., some things may need to stay a certain way to meet user expectations in a legacy product) or other limitations, such as limited ethernet connection speed, mobile app-exclusive features, etc.\n\n## Define the Scope\n\nOne reason we recommend doing design audits periodically is so that product teams do not work alone for too long before they receive any external feedback. This also helps keep the audit scope focused on a few workflows or screens at a time.\n\nIf the product is complex or has never been audited, consider arranging only a few key workflows or screens to be audited. A large scope will “dilute” auditors’ attention and lead to many repetitive comments. The product team should select the part of the product that is either most important to its users or a representative area that can help guide future redesign efforts for other pages.\n\n# Issue Severity\n\nDesign audits identify issues using multiple different severity levels. Severity ratings are determined by their impact on the users. Brightlayer UI recommends using the following severity ratings:\n\nA **top severity** issue is a design flaw that prevents a user from completing a certain task.\n\n\n\nA **high severity** issue greatly confuses or blocks the user, although eventually they might learn to tolerate it.\n\n\n\nA **medium severity** issue makes users hesitate, but they are usually still able to complete their task after some guesswork.\n\n\n\nA **low severity** issue is cosmetic and does not interfere with functionality or usability.\n\n\n\nIn addition, auditors may suggest **features** as well. Features are good-to-have improvements and may be based on designs seen in other Brightlayer UI apps.\n\n\n\nAudit notes may also be tagged with an indicator of whether an issue is about usability or branding. This further helps product teams think about usability systematically.\n\nAuditors are recommended to color code their design audit notes based on severity.\n\n# Understand Audit Results\n\n## Prioritize Issues\n\nTeams must prioritize high-severity issues as they are blocking the application’s functions. These issues must be addressed before the next major release. Meanwhile, mid-severity issues can wait until the next major release, but should still be groomed into the backlog. Low-severity issues are typically considered technical debt.\nHigh-frequency issues — issues that may not be severe but are exposed to users — should also be prioritized.\n\n## Do Not Skip User Testing\n\nA design audit is not meant to replace user testing. While auditors can flag potential issues based on their experience in the design industry, they are not the end user. Teams should conduct user testing to drive major changes while using the design audit as a supplemental tool.\n\n## Schedule the Next Audit\n\nTypically, one design audit is enough to cover most issues in the current version of the user interface. Product teams may consider reaching out to another designer after the existing issues have been pointed out.\n\nWhenever there are major changes to the user interface, product teams should conduct a new design audit to ensure they are still on track.\n\n# How to Conduct Design Audits (For Auditors)\n\n## Prepare Deliverables\n\nA full audit done by the Brightlayer UI team typically includes two parts: detailed notes that capture everything, and a presentation slide deck including only items worth discussing.\n\n\n\nAuditors are expected to build up detailed audit notes as they go through each screen. Once auditors are finished, they may consider selecting a few educational or discussion-worthy topics and adding them to a separate PowerPoint slide.\n\n## Apply Brightlayer UI's Standard\n\n\n\nThere are two parts to Brightlayer UI's design guidelines — [style guide](/style) and [design patterns](/patterns). Each of these describes a set of design standards, which are categorized as follows:\n\n\n\nUser interfaces must be judged under these criteria during design audits.\n\nIn addition, auditors may also employ [Heuristic Evaluation](https://www.nngroup.com/articles/how-to-conduct-a-heuristic-evaluation/) to check UI designs comprehensively.\n\n## Educate the Team\n\nTo help teams develop a human-centered mindset, in addition to pointing out the issues, auditors must also seek to educate their product team to think like designers.\n\n\n\nFor larger products, instead of trying to cover everything in superficial detail, auditors may select 2-3 key interactions and examine them in depth. The auditors’ mission should not be to point out every single UI mistake, but to teach the team how to avoid similar mistakes in the future.\n\n## Prototype Key Features\n\nIf time permits, auditors may select a few key features and prototype their design recommendation. This has a few advantages.\n\n1. Auditors understand better why the product team designed a feature in a certain way.\n2. Auditors get an excellent opportunity for design practice.\n3. A new design placed next to its original design serves as a good side-by-side comparison.\n\n## Summarize Takeaways\n\nWe also encourage auditors to provide an overall summary of their audit findings. This provides teams with quick takeaways that help them estimate their effort in improving the UI design.\n\n## Presentation\n\nAuditors may fine-tune their presentation depending on the expected audience. For example, if the audience is more technical, consider explaining the styling in CSS notations; if they are more on the product design side, auditors may consider showing their raw design process and inviting them for a design critique.\n\nSome team members might feel intimidated by the design audit or feel that the auditor is always right (they aren't). Auditors should encourage teams to challenge the design audit result to foster a better discussion and learn more from the team who knows the product and its history more intimately.\n\nAuditors need to remember to pause from time to time in their presentations for the audiences to catch up — it's likely that many people in the audience are not used to thinking the way a UI designer thinks. Auditors should also ask one member of the audience to take notes.\n\n## Recommend Next Steps\n\nBefore the end of their presentations, auditors should recommend the next steps for teams to act upon. If the auditor has a technical background, they may list a few items as easy-to-fix quick-win items for the developer. If there are major feature suggestions, the auditor may picture how they will fit into the product’s big picture, and what the R&D timeline would look like.\n\n## Improve Brightlayer UI\n\nDuring the audit, if auditors noticed anything worth componentizing or an area where the existing Brightlayer UI standard is too strict, please get in touch with us for a discussion. Many design guidelines in Brightlayer UI today came from real project design audits we performed.\n\n# Design Audit Examples\n\nIf you are an Eaton employee or contractor, you may view the following audit examples (login required).\n\n{/* */}\n\n- [PowerPoint presentation](https://eaton.sharepoint.com/:p:/s/PXBlueDesign&Dev/EVjisdTQEQdJpfyoKNr9ZREBQaKAXzwcLZhKvlyxYfjTow?e=OwlBMg)\n- [Detailed audit notes](https://miro.com/app/board/o9J_lGvtI6E=/)\n\n{/* */}\n"},"/patterns":{"title":"Design Patterns"},"/patterns/account-menu":{"title":"Account Menu","text":"import React from 'react';\nimport { DemoCard, ImageGrid, MaterialDesignDescription, Divider, TOC } from '../../app/components';\nimport PxblueSmallAltIcon from '@brightlayer-ui/icons-mui/PxblueSmallAlt';\nimport Banner from '../../app/assets/design-patterns/account-menu/account-menu-banner.png';\nimport AccountSettingsPage from '../../app/assets/design-patterns/account-menu/account-settings-page.png';\nimport DrawerDetails1 from '../../app/assets/design-patterns/account-menu/drawer-do-and-dont-1.png';\nimport DrawerDetails2 from '../../app/assets/design-patterns/account-menu/drawer-do-and-dont-2.png';\nimport UserMenuContents from '../../app/assets/design-patterns/account-menu/user-menu-contents.png';\nimport AvatarVariants from '../../app/assets/design-patterns/account-menu/avatar-variants.png';\nimport CrowdedDrawer from '../../app/assets/design-patterns/account-menu/crowded-drawer.png';\nimport CrowdedUserMenu from '../../app/assets/design-patterns/account-menu/crowded-user-menu.png';\n\nimport Specs1 from '../../app/assets/design-patterns/account-menu/spec-typography-mobile.png';\nimport Specs2 from '../../app/assets/design-patterns/account-menu/spec-typography-desktop.png';\nimport Specs3 from '../../app/assets/design-patterns/account-menu/spec-drawer.png';\nimport Specs4 from '../../app/assets/design-patterns/account-menu/spec-avatar.png';\n\n{/* KEYWORDS: design pattern user account details settings menu avatar profile */}\n\n# Account Menu\n\n\n\nWhen applications implement a form of [User Authentication](/patterns/user-auth), they must include ways for users to view / update their personal or account information as well as take account-related actions, such as logging out of the application or changing a password. There are several ways to present this information to the user in a Brightlayer UI application.\n\n\n \n \n\n\n# Account Settings Page\n\n\n\nAt a minimum, your application should implement a dedicated account settings page for viewing and editing a user's account details, preferences, settings, etc. This page should also include a way for users to take account-related actions. The style of this page should be consistent with other settings pages in your application, if applicable. If you have multiple settings pages in your application, the account settings should be easily accessible from the top level.\n\n\n\n# In a Navigation Drawer\n\nIf your application is using [Drawer Navigation](/patterns/navigation#drawer-navigation), you can include quick-access user information and actions in the Drawer. Commonly, this involves placing an avatar in the drawer header along with basic information about the user (e.g., their name, username, email address, job title and / or organization affiliation). Additional account actions and a link to the account settings page can be placed at the bottom of the drawer body, just above the footer, if present (see the [contents](/patterns/account-menu#contents) section below).\n\n\n\nThis approach is most effective when there are relatively few account-related actions and is also preferred on mobile where there is limited space in the app bar.\n\nIf you are using a navigation rail, you may place account settings links in the rail, but you will not be able to show specific details about the user. Consider using the {/* */}[User Menu](#via-user-menu){/* */} in this situation or if you are using a primary navigation mechanism other than a drawer.\n\n\n}\n/>\n\n\n# In a User Menu\n\n\n\nAnother way to present user information and actions is with the user menu. The user menu appears as an Avatar in the [App Bar](/patterns/appbar) which opens a menu with the user-related content (see the [contents](#contents) section below).\n\nThis approach is most effective if you have more than three account-related actions, or if you want to present more detailed information about a user since it avoids cluttering the primary navigation drawer.\n\n\n \n }\n />\n \n\n\n# Contents\n\nWhether you are using the drawer or a dedicated user menu component, the content should be very similar.\n\n## Avatar\n\n\n\nAn avatar is used to identify the currently logged-in user / account. It may appear in the drawer header or in the [App Bar](/patterns/appbar).\n\nAvatars can take several forms. Usually, they display a user-selected profile picture. If your application does not support user-selected images, you can default to displaying the user's initials or a [person icon](/style/icon-library?icon=Person&isMaterial=true). You can also elect to show the user's full name or username — this may be particularly useful when your application uses shared or generic accounts (e.g., 'Administrator').\n\nThe avatar should be accompanied by basic information about the user, such as their name, username, email, job title, etc., which can be placed in the navigation drawer header or in the user menu header.\n\n## Account Functions\n\nMost account functions can be located on the account settings page, but you should provide access to the most common / frequent actions in the drawer or user menu as well.\n\nYou should at least include:\n\n- A link to the account settings page\n- A Log Out button\n- Links to terms of service / privacy policy / license information (if applicable)\n\nWhen using the user menu, you will likely have more room available if you wish to include other frequently accessed account functions, such as change password, contact support, etc.\n\n\n \n \n\n\n# Design Specifications\n\n## Mobile\n\n### Navigation Drawer\n\n\n\n### User Menu\n\n\n\n### Avatar\n\n\n\n## Desktop and Tablet\n\nIf certain dimensions are not specified, refer to the dimensions suggested in the mobile section above.\n\n### User Menu\n\n\n\nAlso refer to the design specifications for [Drawer](/patterns/navigation#design-specifications) and [Bottom Sheet](/patterns/overlay#bottom-sheet).\n\n\n\n# Developers\n\nUse the following components to implement this pattern:\n\n**Angular**:\n\n- Angular Material\n - [Side Nav](https://material.angular.io/components/sidenav/overview)\n- @brightlayer-ui/angular-components\n - [Drawer](https://brightlayer-ui-components.github.io/angular/components/drawer/examples)\n - [User Menu](https://brightlayer-ui-components.github.io/angular/components/user-menu/examples)\n\n**React**:\n\n- MUI\n - [Drawer](https://mui.com/material-ui/react-drawer/#main-content)\n- @brightlayer-ui/react-components\n - [Drawer](https://brightlayer-ui-components.github.io/react/components/drawer/examples)\n - [User Menu](https://brightlayer-ui-components.github.io/react/components/user-menu/examples)\n\n**React Native**:\n\n- @brightlayer-ui/react-native-components\n - [Drawer](https://brightlayer-ui-components.github.io/react-native/?path=/info/components-documentation--drawer)\n - [User Menu](https://brightlayer-ui-components.github.io/react-native/?path=/info/components-documentation--user-menu)\n"},"/patterns/appbar":{"title":"App Bars","text":"import React from 'react';\nimport { DemoCard, ImageGrid, MaterialDesignDescription, Divider, TOC } from '../../app/components';\nimport Banner from '../../app/assets/design-patterns/app-bar/appbar-banner.png';\nimport Search from '../../app/assets/design-patterns/app-bar/search-bar/search.gif';\nimport MiniSearch from '../../app/assets/design-patterns/app-bar/search-bar/mini-search.png';\nimport SiteSearch from '../../app/assets/design-patterns/app-bar/search-bar/site-search.png';\nimport PageSearch from '../../app/assets/design-patterns/app-bar/search-bar/page-search.png';\nimport ComponentSearch from '../../app/assets/design-patterns/app-bar/search-bar/component-search.png';\nimport CollapsibleAppBarDynamic from '../../app/assets/design-patterns/app-bar/collapsible-app-bar-dynamic.gif';\nimport CollapsibleAppBarSnap from '../../app/assets/design-patterns/app-bar/collapsible-app-bar-snap.gif';\nimport CollapsibleAppBar1 from '../../app/assets/design-patterns/app-bar/collapsible-app-bar-1.png';\nimport CollapsibleAppBar2 from '../../app/assets/design-patterns/app-bar/collapsible-app-bar-2.png';\nimport SafeAreaError from '../../app/assets/design-patterns/app-bar/safe-area-error.png';\nimport SafeAreaOK from '../../app/assets/design-patterns/app-bar/safe-area-ok.png';\nimport HideOnCollapse from '../../app/assets/design-patterns/app-bar/what-to-hide-on-collapse.png';\nimport AutoVariants from '../../app/assets/design-patterns/app-bar/search-bar/auto-complete-variants.png';\nimport BasicBars from '../../app/assets/design-patterns/app-bar/basic-app-bars.png';\nimport DropdownVariations1 from '../../app/assets/design-patterns/app-bar/dropdown-toolbar-variations-1.png';\nimport DropdownVariations2 from '../../app/assets/design-patterns/app-bar/dropdown-toolbar-variations-2.png';\nimport Specs1Image from '../../app/assets/design-patterns/app-bar/specs-1.png';\nimport Specs2Image from '../../app/assets/design-patterns/app-bar/specs-2.png';\nimport Specs3Image from '../../app/assets/design-patterns/app-bar/specs-3.png';\nimport Specs4Image from '../../app/assets/design-patterns/app-bar/specs-4.png';\nimport Specs5Image from '../../app/assets/design-patterns/app-bar/specs-5.png';\nimport Specs6Image from '../../app/assets/design-patterns/app-bar/specs-6.png';\n\n{/* KEYWORDS: design pattern appbar search collapse collapsible extend prominent toolbar banner header */}\n\n# App Bars\n\n\n\nApp bars, sometimes called toolbars, are often one of the first elements you see in an application. They are primarily used to provide context for where a user is in the hierarchy of the application.\n\n\n \n \n \n\n\n# Basic App Bar\n\n\n\nThe basic app bar provides information about the current screen. Typically, this is a short title that indicates which screen the user is on (e.g., \"Settings\"). However, the app bar can also contain a navigation icon, subtitle, and/or various global action buttons for the screen. When placing actions in the app bar, limit yourself to no more than three. If you have more actions than this, consider grouping them into a menu.\n\n## Dropdown Toolbar\n\n\n \n\n\nA special case of the basic app bar is the dropdown toolbar. This version transforms the simple text subtitle of the app bar into a dropdown menu that can be used to configure the page. For example, you may have a dropdown that allows users to switch between different physical locations on an overview screen.\n\n\n\n## Safe Area\n\n\n\n\n\n# Collapsible App Bar\n\nIn some situations, you may want to present more than just a title and subtitle in an app bar, such as a large graphic, buttons, or multiple lines of text. Collapsible app bars — sometimes referred to as expandable app bars, extended app bars, or prominent app bars — are ideal for this situation. The app bar starts out tall but will shrink as the user scrolls down the page until it becomes a basic app bar.\n\n\n \n \n\n\nCollapsible app bars put a greater emphasis on the app bar content on page load and provide an opportunity to show images pertinent to the page topic. This allows you the flexibility to present an eye-catching banner without permanently reducing the amount of usable space on the page. This pattern is most commonly used for mobile applications, but could also be used for web.\n\n\n\nThe collapsible appbar should transition smoothly between the expanded and collapsed states — this means you will need to account for how the app bar will look throughout the transition. Because elements will disappear as the app bar shrinks, you'll need to use various transition techniques to do this smoothly, depending on your content.\n\n