# Style Dictionary

Central source of truth for design tokens (e.g. colors and icons; eventually
typography, other assets, etc.)

Style Dictionary is configured to run transformations on the design token
definitions and output them in formats that are easily consumed by the client
apps.

## Quick start

This will set up and build the Style Dictionary and process the SVGs under the
`assets/icon/` directory:

```shell
# from style-dictionary
$ pnpm install
$ pnpm build
```

By default, the output will modify files in `ui/app-ui`.

**Note: This does not automatically pull the latest icon assets or color tokens!** You will need
to sync them from Figma first as described in the sections below.

```shell
# from ui/app-ui
$ pnpm style-dictionary # builds design tokens
$ pnpm icon-components # builds icon React components
```

### Syncing Figma icon assets

[This Figma file](https://www.figma.com/design/S04n6UpeU5z9rS1oSCaiyZ/Suno---Storybook?node-id=54-40&t=t9MksqSrQzi6qGjm-1)
contains the icon library that on the design side. This is manually (for now)
synced to the codebase when we want the latest updates.

1. Export the Figma library to SVG. You can `File > Export` or
   `Command + Shift + E`. _Do not manually select the icons!_ You can export the
   entire library at once, which also helps avoid individual icons from being
   left behind.
2. Save the exported icons to [`style-dictionary/assets/icon`](./assets/icon).
   If you know some icons have been deleted, you can remove everything from this
   folder to ensure a "fresh" export.
3. In `ui/app-ui`, run `pnpm icon-components` (or if you are in
   `style-dictionary`, use `pnpm build:icons` instead).
4. Use `git status` to confirm that the changes are expected. You should see a
   subset of the `.svg` files added or updated and all of the `.tsx` files
   updated. Every component will have at least a timestamp update marking when
   they were generated.
5. Commit the changes and open a pull request.

### Syncing Figma color tokens

1. Open the [Design Tokens (W3C) Export](https://www.figma.com/community/plugin/1377982390646186215/design-tokens-w3c-export) plugin in the [Suno - Storybook](https://www.figma.com/design/S04n6UpeU5z9rS1oSCaiyZ/Suno---Storybook?node-id=118-5520&t=h95HQ0nzNyc7AG7T-1) Figma file.
2. The plugin will initiate a download of a zip archive. Unarchive the zip and note the path of the two files that it contains: `app.json` and `palette.json`
3. In `style-dictionary`, run `pnpm build:format-tokens --app=PATH_TO_APP_JSON --palette=PATH_TO_PALETTE_JSON`. The JSON files that you downloaded from Figma will be re-formatted into the expected structure and saved to `tokens/color`.
4. In `style-dictionary`, run `pnpm build:style-dictionary` to re-generate CSS files in `ui/app-ui/src`.
5. Commit the changes and open a pull request.

### Building Style Dictionary and Icons separately

Since output files are timestamped, you may want to avoid modifying them
unnecessarily when the changes are exclusive to a particular type of artifact.

```shell
# from style-dictionary
pnpm build:style-dictionary
pnpm build:icons
```

### Testing

When modifying the build pipeline or debugging, it can be helpful to build to a
test location instead of modifying the app files. That is possible by prefixing
a build command with `NODE_ENV=development`:

```shell
# from style-dictionary
NODE_ENV=development pnpm build
NODE_ENV=development pnpm build:style-dictionary
NODE_ENV=development pnpm build:icons
```

The output is generated in `build/`, which is `.gitignore`-ed.

## How it works

### Design Tokens

Design tokens are defined in JSON files inside the `tokens/` directory. Tokens
must contain a `$value` and `$type`, but can be nested arbitrarily.

`config.js` contains the Style Dictionary configuration that determines how the
design tokens are processed.

### Icons

To update the UI icons, export the entire set from the main Figma library in SVG
format via `File > Export`. Overwrite whatever is in `assets` already, and then
run the `build:icons` to process the icons and generate the React components for
the web app.