# Asphalt Web Tokens

Tokens are the building block of our design system and foundation of theming. Asphalt Web Tokens acts as a bridge between components and theming by abstracting the logic of fetching & processing tokens and theme creation. It works as per the theme specification.

This package exports

- legacy tokens as default export.
- `variables`, `theme` & `getTheme` as named exports
  - **variables**: default tokens in form of CSS variables. Mobile and desktop tokens are included as a nested object under the `mobile` & `desktop` key (i.e., `variables.mobile` & `variables.desktop`).
  - **theme**: default theme in compact format as per theme specification.
  - **getTheme**: function to get theme in any format for a set of tokens, it accepts `tokens` & `format` as parameters.

Theme has three formats -

1. **default** - theme object with all properties of tokens, also referred as expanded form.
2. **compact** - theme object with subset of token properties.
3. **legacy** - object with CSS custom properties and their values.

## Usage

### Npm

```
npm install @gojek/asphalt-web-tokens

import { theme } from “@gojek/asphalt-web-tokens”
```

### Yarn

```
yarn add @gojek/asphalt-web-tokens

import { theme } from “@gojek/asphalt-web-tokens”
```

## Maintainers

### Extracting tokens

Token Studio uses its sync feature to save the raw tokens into the `token.json` file within each theme.

### Generating themes

1. Open `theme-generation.js` script inside the `scripts` folder.
2. Change the import statement `import asphaltWebTokens from "../packages/asphalt-web-tokens/src/lib/token.json" assert { type: "json" };` to required theme's token.json. 

    For example: `import asphaltWebTokens from ../packages/theme-asphalt-web-aloha/token.json { type: "json" }`

3. Change the `themeName` parameter to a relevant name.

    For example: `asphalt-web-aloha`

3. Run the script using `node scripts/theme-generation.js`

**Note:** Generated variables will include mobile & desktop tokens as a nested object under the `mobile` or `desktop` key.

### Contribution guidelines

1. Clone the repository.
2. Do the changes and make a PR against `master` branch.
3. Once its merged and pipeline has succeded
4. Run `yarn run build`
5. Run `yarn run release`
6. Run `git push --follow-tags origin master` to push the tags to origin.
7. Run `npm adduser --registry https://registry.npmjs.org`, make sure you have permission to `@gojek` project on public npm, reach out to @detj for access.
8. Run `npm publish`
9. Create release for the tag manually on gitlab.