# LFDS Core Tokens

Code generation for LFDS design tokens and platform outputs.

## Scope of this README

This README covers **token source and generation workflows** for this package.

- Maintainers: fetch, transform, and build tokens for web/native outputs.
- Consumers: use published package outputs and migration guides.

If you are consuming LFDS web components, prefer consolidated styling via:

- `@lansforsakringar/core-css` (single CSS import)
- `@lansforsakringar/core-components` + `@lansforsakringar/core-css`

For core package release operations, see [packages/core/README.md](../README.md).

## Prerequisites

This package uses [Style Dictionary](https://amzn.github.io/style-dictionary/#/) for token transforms and output generation.

Install dependencies from the repository root:

```bash
npm ci
```

## Fetch Tokens from Figma (Recommended)

You can fetch tokens with the Figma Variables API.

### Setup

1. **Generate a Figma Personal Access Token**

   - Go to [Figma Account Settings](https://www.figma.com/developers/api#access-tokens)
   - Generate a new token with `file_variables:read` scope
   - Note: Requires a "Full" seat in an Enterprise organization

2. **Get your Figma File Key**

   - Open your Figma file in the browser
   - Copy the file key from the URL: `https://www.figma.com/file/{file_key}/...`

3. **Configure environment variables**

```bash
cp .env.example .env
```

4. Add values to `.env`:

```dotenv
FIGMA_ACCESS_TOKEN=your_token_here
FIGMA_FILE_KEY=your_file_key_here
```

4. **(Optional) Fetch from a Branch**

   - If you want to fetch variables from a specific branch instead of the main file
   - First, list available branches:
### Optional: Fetch from a Branch

List available branches:

```bash
npm run list:branches
```

Then set:

```dotenv
FIGMA_BRANCH_KEY=your_branch_key_here
```

### Run Fetch

```bash
npm run fetch:tokens
```

This command:

- Fetches variable collections from the configured Figma file or branch.
- Transforms data to the W3C Design Tokens format.
- Writes output to `/raw-tokens`.
- Creates a backup in `.tokens-backup/`.

Update [CHANGELOG.md](CHANGELOG.md) with fetch time/details for traceability.

## Manual Export (Alternative)

If you do not use the API flow, export LFDS variables manually in [W3C Design Tokens format](https://design-tokens.github.io/community-group/format/) into `/raw-tokens`.

Recommended Figma plugin:
[Design Token Manager](https://www.figma.com/community/plugin/1263743870981744253)

## Generate Outputs

Run:

```bash
npm run build
```

Generated output lands in `/dist` for web plus corresponding native package destinations.

### Android

Colors are generated into:

- `/packages/android/lfds-compose/src/main/java/se/lf/mobile/lfds/foundation/Colors.kt`
- `/packages/android/lfds-compose/src/main/res/values/`

### iOS

Colors are generated into:

- `/packages/ios/Sources/LFDS/Foundation/Color/`

### Web

Web output is generated to:

- `/dist/web/`

Primary CSS entries:

1. **`tokens.css`** (Default): Contains `@import` statements referencing split files (`colors.css`, `dimension.css`, etc.).

   - **Best for:** Projects using bundlers (Vite, Webpack, Next.js) which will handle imports and tree-shaking / inlining automatically.
   - **Pros:** Modular, better for development debugging.

2. **`tokens.full.css`**: Contains **ALL** tokens in a single file with no `@import` statements.
   - **Best for:** Direct usage in HTML `<link>` tags, older systems, or CDNs where extra network requests for imports should be avoided.
   - **Pros:** Single network request, no FOUC (flash of unstyled content) from lazy loading imports.

After generation is solid, publish an new version of the @lansforsakringar/core-tokens package for web.

### Viewer JSON

As part of the build we also emit a flattened payload for documentation apps:

- `/dist/viewer/lfds-tokens.json`
- `/dist/viewer/parsed-tokens.schema.json`

`lfds-tokens.json` contains every resolved token (groups, categories, light/dark/min/max values, alias metadata, CSS variable names, etc.). The accompanying schema mirrors the file and can be used to validate downstream tooling (token viewer, portal, custom docs).

## Structure

`src/build.js` defines the generation pipeline. Platform/mode-specific config files are located in `config/config-{platform}-{mode}.js`.

## Extending

See Style Dictionary docs for extension points:

- [Transforms](https://amzn.github.io/style-dictionary/#/transforms?id=pre-defined-transforms)
- [Formats](https://amzn.github.io/style-dictionary/#/formats?id=pre-defined-formats)