UI Kit

Consuming / Using this project

Contexts

Components in this project rely on several contexts that you need to set up.

i18n keys

Contributing to this project

General Principles

• Stories in storybook are organized following atomic design.
• The props on exported components should be limited to those that are needed and required by design.
• Exposed props should have a corresponding story demonstrating usage
• Exported components should never expose properties that allow setting arbitrary CSS or styling

Write correct HTML

• Components should render correct HTML whenever possible
• Components that can be used for navigation and accept an onClick handler must also accept link props, and render an anchor tag.
• Sections with correct heading levels should be used to ensure the document is properly formatted
  • Each page should only have one h1
  • Pages should not have a h2 beneath an h6 in the same section

Colors, spacing, and sizing components

• Any exported component that provides coloring should do so by generic properties with named values. For example, color="primary" or color="error".
• Any exported component that provides customizing properties related to sizing should use named values for the sizes:
  • If the size determines many aspects of the component's styling, use size prop with appropriate values. For example, on button components, size="medium" will give a medium-sized component
  • If sizing is more granular and only affects a single property, such as border radius, padding, or margin, use individual properties. For example, p="small" will render a component with small padding.
    • An object syntax should also be provided when more granularity is needed. For example, p={{ y: 'small' }} sets a small top/bottom padding for the element.

Sizing in theme

• Specify all font sizes in rem. Specify other sizes, such as border width, border radius, padding, and margin in px.

Default values

• For component props that affect styling, provide defaults whenever possible. Not specifying a default may cause an underlying component such as mui selecting an unintended default value.
• Defaults can be determined based on other props. For example, color may be defaulted based on the variant given.

Partially generic components

• Sometimes, a common set of properties are set together on a component, but introducing a new prop to handle the defaulting is too cumbersome, or could cause confusion. For example, buttons in the system used for confirming and canceling actions should always have the same props. These are really variations, but the button component already has a prop called variant. Adding a similarly named property is likely to lead to confusion. Therefore, a ConfirmButton and CancelButton are exported.
  • Why not use PrimaryButton and SecondaryButton? This can also cause confusion since primary and secondary are values for color on button. Using separate components by intention also allows us to default the label, and restrict props further to just those from the base button component that make sense.

Running storybook

To run storybook:

This will launch storybook at http://localhost:6006

To build storybook:

To manually build components (as will be published to npm):

Building and publishing

This project uses semantic versioning.

Updating the version number and publishing is handled automatically through github actions that are triggered by pull requests.

When developing, use the following workflow:

Local Development

When developing locally, you can see your changes in a project that consumes the ui-kit by using npm link.

To link:

• In ui-kit, run npm run build to create dist folder
• From dist folder, run npm link
• In companion project (e.g., ktt_web), run npm link "@one-market/ui-kit"

To unlink

• In companion project, run npm unlink --no-save <module_name>
• In ui-kit, run npm unlink