@bloom-housing/ui-components

Bloom UI Components

This package is the home of the core UI components for the Bloom affordable housing system, meant to be imported from one or more applications that provide the end-user interface.

Types of Components

Bloom components have been design with the principles of Atomic Design in mind, and some of the directory structure and naming conventions are based on that.

There are also Page Components as a distinct class, which represent larger combinations of components (atomic: organisms) that are meant to be directly imported into specific pages in the system (e.g. a home page).

Locales/Translations

src/locales contains JSON files with translated keys and copy used within all of our packages.

Storybook

The UI components package includes Storybook for easy browsing of the component tree, and is the best way to get started understand what's available (we publish our Storybook). When creating a new component write a default story for the base component and include stories for each state.

To spin up Storybook locally, from within ui-components run:

yarn start

Testing

To run the unit test suite which is built with Jest and RTL, from within ui-components run:

yarn test

or

yarn test:coverage

which generates local coverage reports, useful as you are writing tests to ensure you have encompassed all the states.

To run our accessibility suite which leverages Storybook, from within ui-components run:

yarn test:a11y

Tailwind

• We are using the Tailwind framework to make use of their low-level utility classes in page-level markup and sometimes in components. We configure the settings in tailwind.config.js.

Vendor Plugins

• AG Grid

Style Conventions

• Some styles live in a global folder, but for the most part our components are styled with isolated SCSS files located alongside React component TS files.

• We are currently in the process of migrating components to a second-generation styling convention which relies on CSS variables for design tokens and generally removes @apply Tailwind statements.

• Bloom design tokens include colors, typography settings, sizes, borders, and so forth. They're located in the src/global/tokens folder.

• More information on this process can be found in Styling2ndGen.md.

Naming Conventions

• Our recommendation for class naming methodology is a modified version of BEM. It still uses blocks, sections within blocks and modifiers, but with a subclass syntax for modifiers.

  • Avoid using Sass nesting to build class names

    • Avoid
      • .accordion
        • &-item
    • Preferred
      • .accordion
      • .accordion-item
      • .accordion-item__label

  • Modify with adjectives

    • is-, has-
    • .accordion-item__label.is-open

• Component naming

  • Be wary of naming components based on content, presentation, location, or theming, as this limits the use of the class or becomes confusing
  • Use capitals for React component names
    • SelectButton instead of selectbutton, or Menu instead of menu

• Avoid including any backend business logic in ui-components so that they may be consumed regardless of the backend implementation

General Rules

• Don’t use IDs for styles.
• Don’t nest more than 3 layers deep.
• Don’t fix problems with !important. Use !important purposefully.
• Refrain from using overqualified selectors; div.container can simply be stated as .container.
• Use flex instead of float
• Use grid utilities for uniform grids

Accessibility Considerations

• Storybook A11Y test suite runs on all PRs
• Storybook AXE panel when looking at an individual component can be useful
• Keyboard accessibility
  • Consider aria roles, focus state
• Consider color contrast
• Accessible forms
  • Labels for each input
  • Screen reader labels for inputs with no label
  • Fieldsets for groups
  • Required indicators
• Accessible data tables
• Alt tags for images
• Errors and alert messages