@payfit/unity-themes/README.md

# Unity Themes

The Unity themes package provides a comprehensive design system using TailwindCSS 4, converting all the design tokens of the Unity design system into TailwindCSS utility classes. This is the foundational part of the unity design system and is heavily used by the components package and other unity packages.

> **Note**: Unity Themes v3 is built for TailwindCSS 4. If you're migrating from v0.x, see [MIGRATION-v1.md](./docs/files/MIGRATION-v1.md). For the v3 release, see [MIGRATION-v3.md](./docs/files/MIGRATION-v3.md).

## Installation

Install and configure this package by following these steps:

1. **Install the package and dependencies**

   ```bash
   pnpm add tailwindcss @fontsource/{inter,source-serif-4}
   pnpm add @payfit/unity-themes
   ```

2. **Set up TailwindCSS in your project**

   You need to configure TailwindCSS 4 in your project. This can be done using either the Vite plugin or PostCSS plugin:
   - [Install TailwindCSS v4 in a Vite Project](https://tailwindcss.com/docs/installation/using-vite)
   - [Install TailwindCSS v4 using PostCSS](https://tailwindcss.com/docs/installation/using-postcss)

3. **Import Unity Themes in your main CSS file**

   ```css
   /* /path/to/your/main/styles.css */
   @import '@payfit/unity-themes/css/unity.css';
   ```

   That's it! The Unity CSS file includes all font imports and TailwindCSS configuration.

4. **Use the utility classes in your elements**

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

## JavaScript Utilities

If you need to use JavaScript utilities (like `uyMerge` for class merging), import them normally:

```javascript
import { uyMerge } from '@payfit/unity-themes'

const className = uyMerge('uy:bg-red-l1', 'uy:bg-blue-l2') // 'uy:bg-blue-500'
```

## Usage

Use Unity utility classes with the `uy:` prefix:

```html
<button
  class="uy:bg-surface-primary uy:text-surface-inverted uy:hover:bg-surface-secondary"
>
  Hello Unity!
</button>
```

### Class Syntax

Unity classes use the `uy:` prefix and the prefix goes before any modifiers:

```html
<div class="uy:bg-red-l1 uy:hover:bg-red-l2 uy:md:text-lg"></div>
```

### CSS properties

Access design tokens directly via CSS custom properties:

```jsx
const MyComponent = ({ isHighlighted }) => {
  const bgColor = isHighlighted ? 'var(--color-grayscale-l9)' : 'transparent'
  return (
    <div className="uy:transition-colors" style={{ backgroundColor: bgColor }}>
      Custom styling with design tokens
    </div>
  )
}
```

## Documentation

- **[Architecture](./docs/files/ARCHITECTURE.md)**: Technical details, build process, and internal structure
- **[Migration guides](./docs/4-technical-documents/2-migration-guides.mdx)**: Guides for migrating between Unity Themes major versions
- **[Legacy v0.x](./docs/files/README-v0.md)**: Documentation for the previous version

## Design Tokens

Design tokens are sourced from [Unity's Figma design system](https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library?node-id=0-1&t=rSxQTgD4jTGskNmh-1) and organized in the `tokens/` directory:

```shell
tokens/
├── colors.json      # Color palette and semantic colors
├── typography.json  # Font families, sizes, and text styles
├── spacings.json   # Spacing scale and layout values
├── shadows.json    # Box shadow definitions
├── radii.json      # Border radius values
├── layout.json     # Grid and container sizes
├── sizes.json      # Component and element sizes
└── text.json       # Text-specific tokens
```

## Development

```bash
# Build the package
pnpm nx run unity-themes:build

# Run tests
pnpm nx run unity-themes:test
```

## How to release manually

Add an emoji below:

- 🦄
- 🏰

In some cases, local hr-apps libraries are not published properly, which fails install for `@payfit/payslip-template` afterward.