@payfit/unity-themes 0.0.0-alpha.9 → 1.0.0

package/README.md

@@ -1,101 +1,117 @@
 # 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.
+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.
 
-### Usage
+> **Note**: This is version 1.x of Unity Themes, built for TailwindCSS 4. If you're migrating from v0.x, see [MIGRATIONS.md](./docs/files/MIGRATIONS.md). For legacy documentation, see [README-v0.md](./docs/files/README-v0.md).
+
+## Installation
 
 Install and configure this package by following these steps:
 
-1. Install the package in your project
+1. **Install the package and dependencies**
 
    ```bash
+   yarn add tailwindcss @fontsource/{inter,source-serif-4}
    yarn add @payfit/unity-themes
    ```
 
-2. Import the package and add the preset to your Tailwind CSS configuration file (`tailwind.config.js`):
+2. **Set up TailwindCSS in your project**
 
-   ```javascript
-   const unityPreset = require('@payfit/unity-themes')
+   You need to configure TailwindCSS 4 in your project. This can be done using either the Vite plugin or PostCSS plugin:
 
-   module.exports = {
-     presets: [unityPreset],
-   }
-   ```
+   - [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. Make sure you are including the `@tailwind` directives in your main CSS file:
+3. **Import Unity Themes in your main CSS file**
 
-   ```postcss
+   ```css
    /* /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;
+   @import '@payfit/unity-themes/css/unity.css';
    ```
 
-4. Use the utility classes in you elements!
+   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">
+   <button class="uy:bg-surface-primary uy:text-surface-inverted">
      hello!
    </button>
    ```
 
-### Architecture
+## JavaScript Utilities
 
-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/).
+If you need to use JavaScript utilities (like `uyMerge` for class merging), import them normally:
 
-![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)
+```javascript
+import { uyMerge } from '@payfit/unity-themes'
 
-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.
+const className = uyMerge('uy:bg-red-l1', 'uy:bg-blue-l2') // 'uy:bg-blue-500'
+```
 
-### Build Process
+## Usage
 
-Build the final preset files using the `build` target:
+Use Unity utility classes with the `uy:` prefix:
 
-```bash
-yarn nx run unity-themes:build
+```html
+<button
+  class="uy:bg-surface-primary uy:text-surface-inverted uy:hover:bg-surface-secondary"
+>
+  Hello Unity!
+</button>
 ```
 
-The build process is divided in two stages:
+### Class Syntax
 
-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!_).
+Unity classes use the `uy:` prefix and the prefix goes before any modifiers:
 
-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.
+```html
+<div class="uy:bg-red-l1 uy:hover:bg-red-l2 uy:md:text-lg"></div>
+```
 
-### Testing
+### CSS properties
 
-To run the unit tests for this package, use the following command:
+Access design tokens directly via CSS custom properties:
 
-```bash
-yarn nx run unity-themes:test
+```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>
+  )
+}
 ```
 
-### Design tokens
+## Documentation
 
-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).
+- **[Architecture](./docs/files/ARCHITECTURE.md)**: Technical details, build process, and internal structure
+- **[Migrations](./docs/files/MIGRATIONS.md)**: Complete guide for migrating from v0.x to v1.x
+- **[Legacy v0.x](./docs/files/README-v0.md)**: Documentation for the previous version
 
-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:
+## 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
-<root>
-└── tokens
-   ├── colors.json
-   ├── spcings.json
-   ├── ...
-   └── text.json
+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
 ```
 
-### Notes
+## Development
 
-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.
+```bash
+# Build the package
+yarn nx run unity-themes:build
 
-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.
+# Run tests
+yarn nx run unity-themes:test
+```