Design System Dev Resource
Menu

Docs

coding standards

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=""

developers

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';
  1. If there is Javascript associated with the component, also name its file in the same format: _group-name-component-name.js.
  2. Import the JS file in assets/scripts/toolkit.js, for example:
require("./atoms/03-form-fields-stacked/_text-input-search-field");
  1. 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.

© Banner Health