Habitat - Casavo Design System Library

Welcome to the Casavo design system repository! This is where you can find all the components, guidelines and resources to create amazing user experiences for Casavo. Whether you are a developer, a designer or a product manager, you will find everything you need to get started. Explore the repository and have fun!

Design first

This project is a design driven project, which means we care a lot about the user experience and the aesthetics of our product. We want to create something that is beautiful, functional and easy to use.

Everything in this codebase is a reflection of what has been defined on the related Figma board.

Built on top of

React + Typescript - the library for web and native user interfaces
Vanilla Extract / Emotion - zero-runtime stylesheets in typeScript
Storybook - frontend workshop for building UI components and pages in isolation
Vite.js - next Generation Frontend Tooling

What's included?

You can check the public Storybook to test and experiment with the currently available components.

To sneak peek the incoming new features or components and participate in the discussions you can visit the issue section of this repo, or you can checkout the project's board to have a quick overview of the development status.

Using Habitat in your project

HEADS UP! currently you need

to add the Casavo private NPM registry token,

but we are planning to release this package as a public NPM one in the near future.

install the package in your project (you can use whatever package manager you prefer)

npm i @casavo/habitat

import the style.css and HabitatTheme global class and apply it to top level node of you application.

HEADS UP! the @casavo/habitat/style.css file will also apply a global CSS reset/normalise, it is suggested to remove existing reset solutions.

// src/pages/index.tsx - assuming it is a Next.js application
import Head from "next/head";
import {FC} from "react";

import "@casavo/habitat/style.css";
import {HabitatTheme} from "@casavo/habitat";

export default function Home(): FC => {
  return (
    <>
      <Head>
        <title>Next app + Habitat DS</title>
      </Head>
      <main id="app" className={HabitatTheme}>
        {children}
      </main>
    </>
  );
};

then import and use the components that you need in yout code

// MyComponent.tsx
import {Button} from "@casavo/habitat";

export const MyComponent = (): FC => {
  const variant: string = "secondary";

  const doSomething = (): void => window.alert("button clicked!");

  return (
    <div>
      <Button variant={variant} onClick={doSomething}/>
    </div>
  );
};

you can also import a specific component directly

import {Badge} from "@casavo/habitat/badge"
import {Button} from "@casavo/habitat/button"
import {Checkbox} from "@casavo/habitat/checkbox"
import {Switch} from "@casavo/habitat/switch"
import { H1, H2, H3, H4, H5, H6, Body, Inline } from "@casavo/habitat/typography"

Habitat Components	RSC
Badge	✅
Button	❌
Checkbox	❌
Typography	✅

Local development

Clone the repo and cd into it

git clone git@github.com:casavo/habitat.git
cd habitat

install the NPM dependencies

npm ci

start the Storybook development server

npm run dev

the Storybook instance will automatically open in your browser at http://localhost:6006/.

Please refert to the docs for in depth info on how to work locally.

How to participate?

Before opening issues or pull requests plaese read our code of conduct, then refer to the guidelines described in the "Contributing" section.

For information, requests, bug and inconsistencies alerts join the #habitat-design-system Slack channel.

Updating the Design Tokens (WiP)

This library heavily relies on a set of Design Tokens defined in the Figma board. When the tokens changes on the source board, the designers exports a new .json file that the developers can integrate in the repo and use by following this steps:

copy the .json generated by Figma in the root folder of the project
- if the file has the same name of the existing one just overwrite it
- if the file name change delete the existing one and update the source value in the dictionary.config.json file
from the terminal execute $ npm run update:tokens
this will generate a new plain .json token file in the src/utils folder
commit the changes, push the code and create a new PR as described in the "Contributing" section

(Very short) FAQ

How to use i18n strings that includes HTML entities?

With next-translate we already have a dedicated component that handles the HTML interpolation, you can use it as children to any of our components as following:

import { Body, Inline } from "@casavo/habitat"
import Trans from "next-translate/Trans"

<Body>
  <Trans
    components={{
      strong: <Inline strong />,
    }}
    i18nKey={"context:my-text"}
  />
</Body>

so as you can see we are correctly rendering the HTML markup inside the component and also mapping any <strong> tag defined in the i18n string with an <Inline> Habitat component.

In the case where you are not receiving the i18nKey string but just a string with HTML content within, you can use the html="" prop that we added in every typography components:

import { Body } from "@casavo/habitat"

const HTMLstring = `Some <strong>text</strong> with HTML entities. <br /> Enjoy!`;

<Body html={HTMLstring} />

that prop is a wrapper for React's dangerouslySetInnerHTML, and should be used as a last resort

Is it possible to use Habitat in a Casavo project that is already using other styling solutions?

Yes, so far we did it in project that were using Emotion and Vanilla Extract with another theme and we never got any issue. So this opens the way to a progressive adoption in your existing project.

Can I use this library in a non React or Node.js environment?

There is a related discussion in the issue section of this repository.

Which "parts" can be used as non-React stuff?

the Design Tokens .json file
the CSS reset applied in the style.css file
the vars object exported from /src/utils/theme.ts

License

Code is distributed under the Apache 2.0, Casavo logo and brand are registered trademarks.

casavo / habitat