# Unity Themes

The Unity themes package is a TailwindCSS preset that converts all the design tokens of the Unity design system and implements them as TailwindCSS utility classes. This is one of the foundational parts of the unity design system and is heavily used by the components package.

### Usage

Install and configure this package by following these steps:

1. Install the package in your project

   ```bash
   yarn add @payfit/unity-themes
   ```

2. Import the package and add the preset to your Tailwind CSS configuration file (`tailwind.config.js`):

   ```javascript
   const unityPreset = require('@payfit/unity-themes')

   module.exports = {
     presets: [unityPreset],
   }
   ```

3. Make sure you are including the `@tailwind` directives in your main CSS file:

   ```postcss
   /* /path/to/your/main/styles.css */
   @import '@fontsource/inter';
   @import '@fontsource/inter/500.css';
   @import '@fontsource/inter/600.css';
   @import '@fontsource/inter/700.css';
   @import '@fontsource/source-serif-4';
   @import '@fontsource/source-serif-4/500.css';
   @import '@fontsource/source-serif-4/600.css';
   @import '@fontsource/source-serif-4/700.css';
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   ```

4. Use the utility classes in you elements!

   ```html
   <button class="uy-bg-surface-primary uy-text-surface-inverted">
     hello!
   </button>
   ```

### Architecture

The preset is generated from a set of design token files that follow the Design Token Format Community Group (DTCG) using [Style dictionary](https://v4.styledictionary.com/).

![Diagram explaining the build process of the unity-themes package. It grabs design token files in <root>/tokens, parses them with style-dictionary to create a tailwind preset in typescript format, and then transpiles this preset to commonJS and ESM using Vite](./public/images/unity-themes-diagram.png)

The scripts in the `src` folder create a new style dictionary format that parses the design tokens and generates a TypeScript file that exports the preset.

### Build Process

Build the final preset files using the `build` target:

```bash
yarn nx run unity-themes:build
```

The build process is divided in two stages:

1. **Pre-build:** The scripts in the `src` folder parse the design token files and generate the preset as a TypeScript file in `src/generated` folder (_DO NOT COMMIT THIS FILE!_).

2. **Build:** The preset file is compiled into JavaScript and bundled into a single file using Vite.

The generated artifacts include the compiled JavaScript file and any other necessary files for the package to function properly.

### Testing

To run the unit tests for this package, use the following command:

```bash
yarn nx run unity-themes:test
```

### Design tokens

The design token files are located under the `tokens/` directory, at the project's root. These files were generated from [Unity's design system library in Figma](https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library?node-id=0-1&t=rSxQTgD4jTGskNmh-1).

You can update the tokens from Figma to the themes package using a Figma plugin like the [Design tokens Plugin](https://www.figma.com/community/plugin/888356646278934516/design-tokens). We recommend that you export each token category (colors, spacings, font sizes, etc.) as separated files, like in the example below:

```shell
<root>
└── tokens
   ├── colors.json
   ├── spcings.json
   ├── ...
   └── text.json
```

### Notes

The scripts in the `src/` use the `.mts` format because it allows for better integration with the style dictionary v4.x (which is [only exported as an ES module](https://v4.styledictionary.com/version-4/migration/#es-modules-instead-of-commonjs)) format and provides additional features like stronger typing on the generating scripts.

In the case of this package, this is not an issue because, even though the scripts are esm modules, the final Artifacts generated in the build process are not (in fact, the package exports both CJS + ESM modules). Additionally, we don't directly import the build scripts directly on other files, and they are not meant to be used outside the package, so the module system compatibility is not a concern.
