Hajimari | Hearth Design System 🔗

Figma | Notion |

hajimari (始まり) /.n/ -- beginnings

This repository maintains the component library for Hearth's web (and eventually mobile) app and overall style guide. Hajimari is built following atomic design system guidelines.

Made with ❤️ with npm and react typescript, leveraging MUI for creating and styling components. We use rollup to bundle our JS modules. (Configured with the help of this handy-dandy article about publishing react component libraries)

Getting started

Clone this repository with SSH:

git clone [email protected]:shogun-hearth/hajimari.git

Install dependencies:

npm install

Workflows

The recommended workflow is to work within Storybook to build a component:

npm run storybook

(This loads the stories from ./src/components. A tab should automatically open with Storybook running, but if it doesn't, navigate to localhost:6006)

Contributing Guidelines

Named exports for all components that we want to surface as a part of the npm package--this includes the component itself, as well as any interfaces or props that we would like to export as well.

Use existing component folder structures when creating new components and use the provided template Template.stories.mdx to build a component's story.

Q: Where do new components and stories go?
A: Every new component should live within its own folder, where it is the default export from that folder. The story file lives within the same folder as ComponentName.stories.mdx. In the case of more complex documentation, we can write component stories within ComponentName.stories.tsx, and then use those within MDX documentation. For example, the Card component looks like:

Card
  |__Card.tsx
  |__index.ts
  |__Card.stories.tsx
  |__Card.stories.mdx

Q: What should a new component look like?
A: Beyond exporting the actual component, we also want to export the Props that relate to it. Some prop requirements:

• Reasonable names, so we someone might be able to tell what it's for right away
• A comment above each prop describing its purpose and any other useful notes
• When appropriate, ensure you are extending the existing props of a MUI component you use, so that we can forward props from MUI as well

If this component is an Atom or Molecule, it should be written using syntax that follows the styled() API, as this is the MUI recommended approach for "lower level" components. For larger / more complex components, we can use a combination of the styled() API and the sx prop.

Q: What should a new story look like?

A: Use the provided Template.stories.mdx to create new stories. What's listed in this file is what a story should include at a minimum; more interactivity (or information) is great too!

The title prop determines where in the folder hierarchy a story appears: it should follow a naming convention of Component level > Component Name > Variant. For example:

title: 'Atoms/Button/Outlined Button'

Q: I need to install a new package!
A: There are two kinds of packages we could use here, which are either for using within Storybook or for a component.

1. For Storybook, there are a good amount of libraries installed for our purposes, but we can add them pretty freely.
2. For the actual component library, we want to avoid importing too many external libraries--so only add one if we really, really need to.

IMPORTANT: In both cases, libraries should be installed as devDependencies in order to avoid dependency issues later.

npm i --save-dev <package name>

Design Tokens 101

(TBA)

Resources

• Storybook
  • Rich docs with MDX
• What is Atomic Design?
• Design system examples:
  • Gamut (Codecademy's design system)
  • Storybook's Storybook

Bookkeeping

Continuous Integration

Deployed to Netlify on pushing to the main branch.

TODO / Ongoing progress

1. Converting components not written this way to be written using the styled() API that wraps emotion, which is the MUI-recommended approach.

2. Setting up Jest in order to implement some basic unit tests, at least to start.