Acuity Insights Design System

This is the official repository for the new Acuity design system.

Storybook

Hosted Storybook can be access from Storybook (Main branch)

• You can also access a different branch using: https://[BRANCH_NAME]--6603321f619950844820974b.chromatic.com/

You can also access Storybook locally once you setup this repo, instruction can be found under section IDE Setup > Quick Start.

React + Vite + TailwindCSS

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

Project is using Vite as a build tool. It's a very fast build tool that consists of two major parts:

• A dev server that provides rich feature enhancements over native ES modules, for example extremely fast Hot Module Replacement (HMR).
• A build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production.

Installation

Before installing the library to your project, make sure to have .npmrc file in the root of your project. You should add to this file: //registry.npmjs.org/:_authToken=${NPM_TOKEN}

Add to your .zshrc file NPM_TOKEN env variable (replacing the value with the value that is in 1Password)

export NPM_TOKEN=npm_token_value

Then run:

npm install @takecasper/acuity-design-system

To get the newest version of the library, just run this command again.

To check for the newest releases, you can check the npm page.

To get more information about each release, make sure to check out commit messages on acuity-design-system github repo.

Using the library

To use a component within your project, you can use a component like this:

import { Button } from '@takecasper/acuity-design-system';

IDE Setup

Quick Start

1. Install docker desktop via. https://www.docker.com/products/docker-desktop/
2. To start storybook as a standalone service you can simply navigate to the root project directory and run the command docker-compose up
3. Storybook can then be accessed via localhost:6006
4. Access the prompt shell from the container, you can use the following command: docker exec -it storybook-app bash

   [!NOTE] if you commit code changes without storybook Docker container running in the background, pre-commit validation will execute from your host environment. In that case, you may require to perform npm i to ensure the package dependencies are setup locally. Alternatively, you can simply make sure the docker instance is up and running while commit.

1. Install Dependencies

nvm use 20
npm i

2. Run the app locally

npm run dev

3. Recommended extensions and plugins

1. The official Tailwind CSS IntelliSense extension for Visual Studio Code enhances the Tailwind development experience by providing users with advanced features such as autocomplete, syntax highlighting, and linting.

   • Autocomplete. Intelligent suggestions for class names, as well as CSS functions and directives.
   • Linting. Highlights errors and potential bugs in both your CSS and your markup.
   • Hover Previews. See the complete CSS for a Tailwind class name by hovering over it.
   • Syntax Highlighting. Provides syntax definitions so that Tailwind features are highlighted correctly.

   Setup with clsx lib

   Add following to your settings.json:

    {
   "tailwindCSS.experimental.classRegex": [
    ["clsx\\(([^)]*)\\)", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
   ]
   }

2. Automatic class sorting plugin - A Prettier v3+ plugin for Tailwind CSS v3.0+ that automatically sorts classes based on their recommended class order

3. Tailwind Fold - This extension helps improve the readability of your code by automatically "folding" long class attributes.

• By default, automatic folding is enabled, but you can customize this behavior in the settings. Quickly toggle folding using the keyboard shortcut Ctrl+Alt+A

Publishing to NPM

To trigger build and publishing to npm automatically, follow this guide.

Essentially, the github action for publishing a new library version will be triggered only when certain keywords are included in the git commit message, and only on commits to the main branch (fix, feat, perf, etc.). Therefore, we should make sure that each time we squash and merge our feature branches to the main branch we should include those keywords in the commit message, if we want to publish a new lib version. Certain changes don't need to trigger lib publishing, such as adding new stories, Storybook changes or tests.

Development

• For faster search and usage of tailwind utility classes use Tailwind Cheat Sheet

Including components in the library build

Once components are ready to be used, they should be imported and exported in the index.ts file in the src directory, this will include them in the main build and make available for users of the library.

It's important to export all the types and interfaces together with the components, so they can be also exported in the type declarations file created by the build (index.d.ts file in the dist directory). In this way library users can import those types in their projects that are using TS. Example:

<!-- index.ts file -->
import Button, { ButtonProps, ButtonVariant } from './components/Button/button';

export type { ButtonProps, ButtonVariant };
export { Button };

Project structure

Best practices

Styling with Tailwind

Prepend utility classes with ds-

We are having an internal convention to style all components using ds- prefix. The reason for this is to avoid conflicting classes in projects that are using design system library. The prefix option lets us configure a prefix we want added to the beginning of every Tailwind class to avoid conflicts. But if you enable it, you need to make sure you actually use that prefix in your HTML files.

Consequently, regular classes such as text-neutrals-black, flex-row, etc., must be prefixed with a designated prefix. Subsequently, styling our components in the design system will require utilizing prefixed classes, such as ds-text-neutrals-black or ds-flex-row. For pseudo-classes, the ds prefix should be appended after the pseudo-class indicator. For example hover:ds-text-neutrals-white,active:ds-bg-acuity-blue, etc.

Source

Reason for this.

Add preflight class to component wrappers

Tailwind includes a useful set of base styles out of the box that they call Preflight, which is basically just normalize.css plus a thin layer of additional more opinionated styles.

Since these styles are usually targeting elements, and root html scope, once that css is bundled with our component library this exported CSS might interfere with the styling of the html elements in other projects the library is being used in. This specifically creates conflicts in projects where Tailwind CSS is not the CSS library of choice and where the global styling/or base styling looks different than what Tailwind team decided to do in Tailwind Base/aka Preflight.

We decided on using tailwindcss-scoped-preflight Tailwind plugin, that disables the preflight on the global level and enables it on the scoped level. This plugin is limiting the scope of Tailwind's opinionated preflight styles to the customizable CSS selector. In that way we can control where exactly in DOM to apply these base styles - usually it's our own components (not the 3rd party). We are using isolateForComponents strategy and added a selector preflight. We should add this class for the wrapper element of the new components being added to the library to enable Tailwinds base styles.

Add ds-form-* class to input components to apply tailwind forms styles

We are using @tailwindcss/forms plugin to reset all the browser styles for inputs so we can style it more easily. To avoid conflicts within other projects we are using the class strategy which means that we need to add the form class to our input components. As we are using prefixes in our project, we need to prefix each of those classes with ds. Example on how to use classes to style input components.

Adding new components

For easier development and conditional rendering of tailwind's utility classes it is recommended to use the following 3 libraries when adding new components:

1. clsx - A tiny (239B) utility for constructing className strings conditionally. Also serves as a faster & smaller drop-in replacement for the classnames module.
2. tailwind-merge - Utility function to efficiently merge Tailwind CSS classes in JS without style conflicts:

import { twMerge } from 'tailwind-merge'

twMerge('px-2 py-1 bg-red hover:bg-dark-red', 'p-3 bg-[#B91C1C]')
// → 'hover:bg-dark-red p-3 bg-[#B91C1C]'

3. class-variance-authority - Specifically important to follow these guidelines for using cva lib with Tailwind CSS Example using cva with tailwind merge:

import { cva, type VariantProps } from "class-variance-authority";
import { twMerge } from "tailwind-merge";

const buttonVariants = cva(["your", "base", "classes"], {
  variants: {
  intent: {
  primary: ["your", "primary", "classes"],
  },
},
  defaultVariants: {
  intent: "primary",
  },
});

export interface ButtonVariants extends VariantProps<typeof buttonVariants> {}

export const button = (variants: ButtonVariants) =>
twMerge(buttonVariants(variants));

4. Define common or known unique use cases as stories so they will automatically be picked up by both a11y test and UI test.

PR Review process

• Creating commits:

  • The first commit of the new branch should include the context, description, and Jira ticket in the bottom of the commit.
  • When the feature is approved and we squash all the commits from the pr branch into one and then merge into the main branch, git will pick up the first commit message and add asterisks with subsequent commits, that means you can adjust the final commit description based on the secondary commits, and because you added the JIRA link in the first commit, from then on it will be tracked by JIRA.

• Using "Squash and merge" option when merging pr branches into main. Here is some documentation about why to use squash and merge.

• Two approvals are needed per open PR

Expanding the ESLint configuration

If you are developing a production application, we recommend updating the configuration to enable type aware lint rules:

• Configure the top-level parserOptions property like this:

export default {
  // other rules...
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    project: ['./tsconfig.json', './tsconfig.node.json'],
    tsconfigRootDir: __dirname
  }
};

• Replace plugin:@typescript-eslint/recommended to plugin:@typescript-eslint/recommended-type-checked or plugin:@typescript-eslint/strict-type-checked
• Optionally add plugin:@typescript-eslint/stylistic-type-checked
• Install eslint-plugin-react and add plugin:react/recommended & plugin:react/jsx-runtime to the extends list