Bloom UI ComponentsThis 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 ComponentsBloom 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).
src/localescontains JSON files with translated keys and copy used within all of our packages.
StorybookThe 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
TestingTo run the unit test suite which is built with Jest and RTL, from within
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
- 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
- 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
- Bloom design tokens include colors, typography settings, sizes, borders, and so forth. They're located in the
- More information on this process can be found in Styling2ndGen.md.
- 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
- Modify with adjectives
- Avoid - .accordion - &-item - Preferred - .accordion - .accordion-item - .accordion-item\_\_label
- is-, has- - .accordion-item\_\_label.is-open
- Component naming
- 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
- 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
- Storybook A11Y test suite runs on all PRs
- Storybook AXE panel when looking at an individual component can be useful
- Keyboard accessibility
- Consider color contrast
- Accessible forms
- Accessible data tables
- Alt tags for images
- Errors and alert messages