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

The library is built to run on your app's React, MUI and Emotion rather than bundling its own copies (one copy per page is required for React and for MUI theming to work). Make sure these peer dependencies are installed in your app:

npm install react react-dom @mui/material @mui/icons-material @mui/system @mui/utils @emotion/react @emotion/styled react-toastify

Supported ranges: react/react-dom 18.2+ or 19, @mui/* 7, @emotion/* 11, react-toastify 11. @mui/x-data-grid is bundled with the library, so it does not need to be installed at runtime; it is an optional peer because the AcuityDataGrid prop types reference it, so install it if you use that component and want its props typed. npm run smoke:consumer installs the built package into a throwaway project with a given React/MUI version and renders a component with it (see scripts/consumer-smoke.mjs).

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';

Import the stylesheet once at your app's entry point:

import '@takecasper/acuity-design-system/style.css';

MUI-based components read the host MUI theme. To render them with the design system's own theme, wrap them (or your app root) in AcuityMuiThemeProvider:

import { AcuityMuiThemeProvider } 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 a release branch (fix, feat, perf, etc.). Therefore, we should make sure that each time we squash and merge our feature branches to a release 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.

Commit keywords and version bumps

The version bump is derived from the commit message on the release branch (Conventional Commits):

• fix: → patch release (e.g. 2.0.0 → 2.0.1)
• feat: → minor release (e.g. 2.0.0 → 2.1.0)
• feat!: / fix!: or a BREAKING CHANGE: footer → major release (e.g. 1.27.13 → 2.0.0)
• chore:, docs:, test:, story-only changes → no release

Because we squash and merge, it is the squash commit message that semantic-release reads — not the individual commits on the feature branch. Make sure the squash message carries the right keyword.

Branching and release strategy

The release configuration lives in .releaserc.json and the CI workflow in .github/workflows/publish.yml. We maintain more than one release line so we can ship a new major version without breaking consumers still on the previous one.

| Branch | Purpose | | ------ | -------------------------------------------------------------------------------------------------- | | main | The current major line. Merges here publish the latest version on npm (currently the v2.x line). | | 1.x | Maintenance line for v1. Merges here publish v1 patch/minor releases for consumers pinned to ^1. |

How consumers are protected: consumers depend on a range such as ^1.27.0, which never resolves to 2.x. Publishing 2.0.0 from main therefore does not affect existing v1 apps — they stay on v1 until they explicitly upgrade. The 1.x branch lets us keep shipping fixes to those apps in parallel.

[!IMPORTANT] > Never merge 1.x into main, and never merge main into 1.x. The two branches represent different major versions with intentionally divergent, breaking code. Merging them together would drag breaking changes into the v1 line (or v1 code back into v2) and corrupt the release history semantic-release relies on.

To move a change across lines (e.g. a bug fix that applies to both v1 and v2), apply it independently to each branch — cherry-pick the individual commit, or copy just the relevant files — rather than merging the whole branch. Feature branches should be opened against, and squash-merged into, the single release branch they target.

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