Guidelines

Each component has dedicated guidelines on when or when not to use it and what's the best way to apply that component. There are also general guidelines around Hightouch UI design system overall.

#Never override the built-in styling of the component

If a component doesn't fit your requirements, double check if you're using the right component for your use case by reading its guidelines in the documentation. Then, post in #hightouch-ui Slack channel about missing features in the component you want to use and why they're needed.

Every change to the design system is important, because it immediately affects the its consistency and usage long term. It's crucial to discuss the path forward together.

#Custom UI elements

As we're incrementally moving to Hightouch UI in the app, we'll be adding more components to the library for you to use. While we're still in that process, there will be times when you'll need to implement a completely custom component that's unlike anything we have in Hightouch UI.

In that case, Hightouch UI offers an escape hatch — a Box component. It's a re-exported Box component from Chakra UI, which can render any element with any style you want. Feel free to use it when necessary and it'd be great if you posted in #hightouch-ui Slack channel when you do, so that we can discuss how to avoid it and bring that code into Hightouch UI itself.

#New components

If you notice that you often repeat the same UI code, it's a good sign that it's time to extract it into a new component. Great first step is to keep that component inside an app repository first as a sort of a trial period. If you or others keep reaching for that component in your work and it consistently works, that means it's stable and mature enough to live inside Hightouch UI itself.

To add a new component to Hightouch UII:

1. Add code for it in src folder.
2. Export it in src/index.ts file.
3. Write documentation for it in docs/pages/components folder. Stay consistent with formatting and sections of the other existing components. Make sure to include guidelines on when or when not to use your component.
4. Add a link to the documentation page you just created in docs/components/mdx-layout.js file.
5. Add a preview of your component to docs/lib/components.js file. This preview is displayed on the documentation's home page. It doesn't have to actually render your component, it's preferable to create a small illustration of how it looks. See other components there for inspiration.
6. Submit a pull request. Include the context on why this component is needed and where it's used.

#Icons

We use Heroicons as a primary icon set in our app. There are might be cases where Heroicons doesn't include an icon you're looking for. In this case, check if you can find an icon with a close enough meaning first. If that's not an option, post in #hightouch-ui Slack channel about a missing icon and we will all look for a replacement that matches the style of Heroicons.