Docs

The following is a work-in-progress list of standards we follow on the Banner Health design team when working on front end development.

General

• Keep your code clean - if it starts getting long or complicated, comment to explain what’s going on.

HTML

• Use the correct HTML tags - <a> tag for links, <button> tags for buttons that trigger something (not links), <input type="submit"> for form buttons etc. This is good for accessibility and saves time when writing JS to interact with these items.
• Add classes to every piece of HTML code that will need styling. Allows for easy searching in CSS files, and more specific styling, which can be needed to overwrite some sites' existing styles.

CSS

• Don't rely on Bootstrap, Foundation, etc. classes when styling a component, because a site that uses this component may not have those frameworks.
• When styling a page or site, organize the order of your Sass styles according to the layout of the site (i.e. global styles, <header> styles, <main> styles, <footer> styles).
• Avoid global styles when possible, unless it does apply to ALL those selected - for example, styling all links to be blue won't work when we have design system button links that have a white font color.
• Always use the Banner Health brand color Sass variables when using a color in your styles. If the mockup references a color not on that page, ask the designer if it was intentional or if the mockup is incorrect.
• Try not to nest too deep within your Sass files, especially when building a new design system component. One parent class is enough for a component, with all of its children components living within that.
• Media queries should usually be nested within each style declaration, so it's easy to find all the styles related to each selector.
• For the design system, we use a less strict version of BEM. Specifically, we name a component’s parent and children with similar class names, and use BEM's double-dash modifier. For example, this component’s parent class is bh-notification. See the example code below:

<div class="bh-notification">
    <p class="bh-notification-copy">This is copy for a notification.</p>
</div>

<div class="bh-notification bh-notification--full">
    <p class="bh-notification-copy">This is copy for a notification.</p>
</div>

.bh-notification {
    //parent element's styles

    &-copy {
        //child's styles
    }
    
    &--full {
        //specific styles for the modified version of bh-notification
    }
}

JS

• Clean up console logs when you're done building a component.
• Use descriptive variable and function names. For example, a function named validateDOBLength tells you what the function does, where a vague function name validate does not. We can minify the code after to keep the file size small.
• When building out a component, assume that it will be used multiple times on the same page. JavaScript will need to capture each instance on the page and work correctly.

Accessibility

• Keep accessibility in mind throughout building a component, some examples:
  • Add aria-label to buttons or other components where the UI isn't particularly clear. For example, if a filter list button says "Save", give it an aria-label="Save filters"
  • When using inline SVG code, add aria-hidden="true" and focusable="false" to the <svg> tag so screen readers don't read their titles
  • If you're building a component that has similar features to another component, use that one as an example of its accessibility needs
  • If you're using the <img> tag, include an alt tag with good description. If the image is an icon used as decoration, leave the alt tag blank: alt=""

Adding a component to the Design System

Once a component has been added to the Design System in Sketch, its code can be added here. Use the following instructions when adding a new component.

1. Name your HTML file in the following format: group-name-component-name.html where group-name is an optional prefix referencing the subgroup in which the component belongs. For example: text-input-search-field.html, where text-input is the group name, and search-field is the component name. This keeps similar components grouped together as they are arranged alphabetically.
2. If there are images associated with your component, put them in the following directory: src/assets/toolkit/images
3. All components are styled using Sass. Name your Sass file _group-name-component-name.scss. It must have the exact same name as the HTML file (plus the underscore at the beginning), so the Sass code can automatically be added to the component's code on its page.
4. Import the Sass file in assets/styles/toolkit.scss, for example:

@import 'atoms/03-form-fields-stacked/_text-input-search-field';

5. If there is Javascript associated with the component, also name its file in the same format: _group-name-component-name.js.
6. In the component's HTML file, you may need to add further context to the component at the top of the document (shown in code below). There are currently 3 instances where this is useful.
   • If Javascript is associated with the component, add the javascript: true property/value to the context at the top of the document. This lets Fabricator know that there will be an associated Javascript file that should be shown when viewing the component.
   • For the rare occasion where CSS is not needed for a component (ie. showing just the SVG code for an icon), add hidecss: true. This lets Fabricator know it does not need to look for a Sass file.
   • This is also where you can add notes related to the component (for example: the optional modifier Sass classes, or if referencing styles/scripts needed from another component).
   • An example of all 3 uses is below:

---
javascript: true
hidecss: true
notes: <strong>Modifier classes:</strong> <span>bh-search-field--large</span><br><strong>Notes:</strong> You will need the following images for this component&colon; <a class="ref-link" href="icons.html#utility-icons--search-icon" target="_blank">Search icon</a>
---

<input aria-label="Search" type="search" class="bh-search-field" placeholder="Placeholder" />

Starting the Fabricator project locally

1. Navigate to the dsm-fabricator folder within the repo.
2. Run gulp serve --dev

Building the project

1. When a new component is created, run gulp to rebuild the site to include the new component.

Component delivery

Feel free to use this Design System as a delivery tool to provide components and code as needed. There are a few options for delivery:

• When delivering to an internal team that will need the coded components, use the following link, which has queries that shows the components' code and notes by default: https://bhdgwebdesignsa.z22.web.core.windows.net/?code=t&notes=t
• When delivering to an internal team that will not need the components' code or notes related to the code, use the standard link: https://bhdgwebdesignsa.z22.web.core.windows.net/
• You can also link to a specific component by clicking the link icon next to the component's name, which will give you its direct URL in your browser's URL bar.

Jun 21, 2024

New progress indicators, new tooltip variation

A new progress indicators section has been added in Atoms which includes a circular indicator and a variation.

Tooltip 1 has been updated to include a new white background variation.

Apr 12, 2024

New colors, radio button & checkbox updates

The following colors and their variables have been added to the Colors and Site usage pages for use throughout the design system: rating, true black, and 8 profile colors.

The radio button and checkbox form field controls have been updated to match the new Figma styles, and now include error and disabled states.

Feb 27, 2024

New branding section and star rating component

A new branding section and 6 logos were added to the Atoms page.

The star rating component has been added to the Molecules page.

Jan 29, 2024

Progress bar

The progress bar component has been added to the site.

Nov 14, 2023

New icons

Several new utility icons have been added to the Icons page.

Oct 9, 2023

New visit type toggle button

The visit type toggle button has been added to the Atoms page.

May 15, 2023

8 new icons

The icons page has been updated with 8 new brand icons from the Figma design system.

April 17, 2023

32 new icons

The icons page has been updated with 32 new icons from the Figma design system.

January 26, 2023

Display and headings fonts updated to new font, Utopia

Additionally, all text styles have been updated to remove their color, since color is often not $color-banner-black.

December 8, 2022

New inline notifications for information, confirmation, and errors

These are inline versions of the existing trigger notifications, available here.

August 3, 2022

New CSS custom properties for all colors and fonts

In addition to SCSS variables, CSS custom properties are now available to use. They can be seen on the Colors page for easy copy/pasting, and are also shown on Site usage for incorporating them into your project as a whole.

November 10, 2021

New icons and related icon component

1 new icon component was added to the Atoms page: Location map pin

2 new icons were added to the utility icons: Map pin and Map pin b

October 26, 2021

New icons

1 new icon was added to the brand icons: Video visit

2 new icons were added to the utility icons: Calendar and Map zoom out

May 19, 2021

Helper scripts page

A new Helper scripts page has been added to the site. Each script on this page can be added on to a site without any HTML or CSS necessary. The first script has been added to it, Browser and device info

May 10, 2021

New full-screen mobile dialog option

The Dialog desktop component has been optimized for mobile as well, with a new full-screen mobile option, for when the dialog has lots of content

March 23, 2021

New icons

2 new icons were added to the utility icons: Star outline and Star filled

February 19, 2021

New heading text style

A new heading "H1b" has been added to Headings

Icon updates

The Favorite icon and Favorite alt icon have been updated

Body text class updates

Updates to body copy: the body-1-medium and body-2-medium classes have been changed to body-1-strong and body-2-strong

November 19, 2020

Button state updates

The hover, active, and loading states were updated on the following buttons: Outlined 1 button, Outlined 2 button, Outlined 3 button, and Text button

May 26, 2020

New icons

2 new icons were added to the utility icons: Pin and Pin alt

May 13, 2020

Banner Atria Launches

We will be adding and modifying components frequently. Check here for brief rundowns of what's new.