# Custom Formatter

## Context

To generate theme preset files from the design token JSON files, use custom formatter for [Style Dictionary](https://amzn.github.io/style-dictionary/#/README).

One of the token is transformed into an object like this:

```ts
{
  value: '#006917',
  type: 'color',
  fileRegExp: /tokens\/color\/color.json/,
  // other...
}
```

The formatter will convert each object to an token object.

## Panda CSS Preset Formatter

The `fileRegExp` is used to determine which token the object represents in terms of Panda CSS.

The JSON file in the `tokens/core` directory are treated as tokens, others are treated as semanticTokens.

The structure of semantic tokens in JSON and Panda CSS is different, so they cannot be used as they are.
For example, if `"$value":"{typography.font-size.body}"` is specified in json, Panda CSS uses `"value":"{fontSize.typography.font-size.body}"`.
The prefix must be added to indicate which token it is at the beginning.

When the Style Dictionary converts a json to a token object, if a semantic value is used in the JSON, the `value` property will be populated with the primitive value of the reference.
Therefore, put the value directly in the object for Panda CSS instead of the reference value to the token.

Finally, Custom formatter generate the preset object to `dist/presets/pandacss.ts`.

### How to Add New Token for Panda CSS

If new design token JSON files are added, they must be appended to `tokenFilesMapper.ts`.

The `themeType` key specifies whether the JSON file should be used as a `token` or `semanticToken` in Panda CSS. Basically, use `semanticToken`.

The `tokensType` key specifies which Panda CSS tokenType to use. See [the TokenTypes reference in the official document](https://panda-css.com/docs/theming/tokens#token-types) for available values.

The `filePath` key should be a relative path of the JSON file starting with `tokens/`.

## Tailwind CSS v3 Preset Formatter

Similar to the Panda CSS formatter, a custom formatter has been created to generate a Tailwind CSS v3 preset configuration from design token JSON files.

The formatter follows the Tailwind CSS theme structure and maps the design tokens to the appropriate Tailwind CSS theme properties based on the mapping defined in `tailwindTokenFilesMapper.ts`.

`box-shadow` token has a different format, so formatter converts shadow values to match Tailwind's boxShadow string format.

Finally, Custom formatter generate the preset object to `dist/presets/tailwind.ts`.

### How to Add New Token for Tailwind CSS v3

If new design token JSON files are added, they must be appended to `tailwindTokenFilesMapper.ts`.

The `tokensType` key specifies which Tailwind CSS tokenType to use. See [Tailwind's theme structure](https://github.com/tailwindlabs/tailwindcss/blob/v3/stubs/config.full.js) for available values.

The `filePath` key should be a relative path of the JSON file starting with `tokens/`.

## Tailwind CSS v4 Theme Formatter

A custom formatter for Tailwind CSS v4 that generates a CSS file with the `@theme` directive, aligning with Tailwind CSS v4's CSS-first philosophy.

Unlike Tailwind CSS v3 which exports a JavaScript configuration object, Tailwind CSS v4 uses CSS variables with specific namespaces that map to utility classes:

- `--color-*` → color utilities (bg-_, text-_, border-\*)
- `--font-*` → font-family utilities
- `--text-*` → font-size utilities
- `--spacing-*` → spacing utilities (p-_, m-_, gap-_, w-_, h-\*)
- `--radius-*` → border-radius utilities
- `--shadow-*` → box-shadow utilities
- `--ease-*` → transition-timing-function utilities

The formatter uses the same token mapping defined in `tailwindTokenFilesMapper.ts` but converts them to CSS variable format instead of JavaScript objects.

**Special handling:**

- **Multi-layer shadows**: Combines multiple shadow tokens (e.g., `elevation-plus-1-shadow-1` and `elevation-plus-1-shadow-2`) into a single CSS value with comma-separated shadows
- **Easing functions**: Transforms arrays to `cubic-bezier()` format
- **Font families**: Converts arrays to comma-separated strings

Finally, the formatter generates the CSS file to `dist/css/tailwind-v4.css`.

### How to Add New Token for Tailwind CSS v4

The Tailwind CSS v4 formatter reuses the token mapping from `tailwindTokenFilesMapper.ts`. When adding new token files:

1. Add the mapping to `tailwindTokenFilesMapper.ts` (shared with Tailwind CSS v3)
2. Ensure the `themeProperty` has a corresponding namespace in `NAMESPACE_MAP` in `tailwindV4ThemeFormat.ts`
3. If the token type requires special formatting (like shadows or easings), add handling in the formatter

See [Tailwind CSS v4 Theme Documentation](https://tailwindcss.com/docs/theme) for namespace conventions.

## Reference

- [Panda CSS](https://panda-css.com/)
- [Style Dictionary](https://amzn.github.io/style-dictionary/#/)
- [Tokens - Panda CSS](https://panda-css.com/docs/theming/tokens)
- [Custom formats - Style Dictionary](https://amzn.github.io/style-dictionary/#/formats?id=custom-formats)
- [Tailwind CSS v3 Theme Configuration](https://v3.tailwindcss.com/docs/theme)
- [Tailwind CSS v4 Theme Variables](https://tailwindcss.com/docs/theme)