
Library name:       fuegokit/tokens
Version:            0.14.0
Repository URL:     https://github.com/mgo-af/fuegokit-tokens
License:            ISC
License Text:       # Fuegokit Tokens

Multi-ecosystem design tokens package for Fuegokit, a design system for designing, building, and extending Appfire products.

Read the docs at [https://fuegokit.design/tokens](https://fuegokit.design/tokens).

To run storybook from the project root run `yarn tokens:storybook`.

To run docs from project root run `yarn tokens:docs`.

## Taxonomy

Design tokens represent single sources of truth to name and store semantic design decisions.

They map a semantic name (`color.surface.default`) to a scale token (`neutral.000`).

```json
{
  "scale": {
    "neutral": {
      // <-- core token color group
      "1100": {
        // <-- core token scale value
        "value": "#EBECF0", // <-- W3C specification $value
        "type": "color", //<-- W3C specification $type
        "attributes": {
          // <-- attributes
          "role": "scale", // 'scale' | 'semantic' | 'component' | 'global'
          "theme": "default", // 'default' | 'atlassian' | | 'brand' | 'mktg' | 'aui' | 'fk-monday'
          "introduced": "0.9.1", // when the token was introduced to the system
          "state": "active" // 'active' | 'deprecated' | ('removed' tokens are removed and not published)
        }
      }
    },
    "red": {
      // etc
    },
    // ...
    "text": {
      "default": {
        "value": "{scale.neutral.1000}", // <-- W3C specification $value; often resolves to an alias provided by a `scale` token
        "type": "color", //<-- W3C specification $type
        "description": "Use for primary text, such as body copy, sentence case headers, and buttons.", // <-- description must be outside of attributes
        "attributes": {
          "role": "semantic",
          "theme": "default",
          "introduced": "0.9.1",
          "state": "active"
        }
      }
    }
  }
}
```

## Fuegokit Tokens SDK

The Fuegokit Tokens SDK provides ready-to-consume JavaScript, TypeScript, CSS and Tailwind CSS product themes for use in your application. It is a set of tools and utilities that serve as a single point of entry for design tokens in different product ecosystems and contexts. 

**⚠️ Note, the SDK is in an early beta, and no warranty is implied. Proceed with caution.**

### Features

#### Dynamic theme switching

The Fuegokit Tokens SDK allows you to dynamically change themes provided by design tokens. It allows teams to "design once, ship everywhere". And for developers, that means that you may write code once, and that you can then ship the same code into different product ecosystems, using the appropriate design language for each.

#### Intellisense 

Typescript SDK offers full integration with any modern IDE. We provide a `d.ts` files so it should work with Javascript SDK as well.

![Intellisense](./sdk-ide-hints.png)

### Installation

SDK is a part of `@fuegokit/tokens`.

```bash
yarn add @fuegokit/tokens
// or
npm install @fuegokit/tokens
```

Access to Fuegokit npm packages, source code repositories, and some content is limited to Appfire staff. For support with Nexus, 
please contact [Appfire Engineering Operations.](https://appfireteam.atlassian.net/wiki/spaces/experience/pages/95441944614/Install+our+npm+packages)

A CDN to deliver compiled CSS and SDK is on our roadmap.

### Quick start

Get set up for success with the Fuegokit Tokens SDK.

#### Loading themes

Use the loadTheme function to match your application's theme with a host platform or product ecosystem.

```typescript
/**
 * Typescript
 */

// Import Fuego object
import { Fuego } from '@fuegokit/tokens/dist/sdk/ts';

// Import Theme
import mondayLight from '@fuegokit/tokens/dist/sdk/ts/themes/monday-light';

// Load theme
Fuego.loadTheme(mondayLight);



/**
 * Javascript
 */

// Import Fuego object
import { Fuego } from '@fuegokit/tokens/dist/sdk/js';

// Import Theme
import mondayLight from '@fuegokit/tokens/dist/sdk/js/themes/monday-light';

// Load theme
Fuego.loadTheme(mondayLight);
```

```text
/**
 * CSS
 */
 
Import theme as a CSS file from:
@fuegokit/tokens/dist/sdk/css
and add it to your page.

import '@fuegokit/tokens/dist/sdk/css/monday-light.css';
```

```text
/**
 * Tailwind + Typescript or Javascipt
 */
 
There is a ready to use tailwind config in:
@fuegokit/tokens/dist/sdk/tailwind

You can use it in your app, then use TS or JS SDK to load a theme.
```

#### Getting token values - dynamic

`Fuego` object contains `themeGet` function which can be used to get the token value. Important, you don't need to trigger re-render of your component when you switch between themes.

```jsx
function SignatureComponent({firstname, lastName}) {
	return <span style={{ color: Fuego.themeGet('text-subtle') }}>
		{ firstname } { lastName }
	</span>
}
```

#### Extending themes

We are aware that `Fuego` object and it's themes provide a minimal set of reusable tokens. If you need a value that is not avaiable in that set you can easily extend your theme.

```typescript
type ThemeExtensionTokens = 'gantt-bar-highlight-text' | 'gantt-bar-highlight-background';

const tokenToValueMap = new Map([
	['gantt-bar-highlight-text', 'value'],
	['gantt-bar-highlight-background', 'value']
]);

Fuego.loadThemeExtension(tokenToValueMap);
Fuego.themeGet<ThemeExtensionTokens>('gantt-bar-highlight-text');
```

When using it in Typescript you will have full IDE intellisense. This mechanism is flexible, for now there's no common way of delivering tokens map, it all depends on your code.

#### Aliasing Fuegokit tokens

There might be a need to use a Fuegokit token but with a bit different name. `Fuego` provides an easy solution for that.

```typescript
type ThemeAlias = 'gantt-bar-highlight-text' | 'gantt-bar-highlight-background';
Fuego.addUpdateAlias<ThemeAlias>('scale-yellow-600', 'gantt-bar-highlight-background');
Fuego.themeGet<ThemeAlias>('gantt-bar-highlight-text');
```

#### Watching on theme load and unload events

```typescript
const clearOnThemeLoad = Fuego.onThemeLoad(() => console.log('Theme changed'));
const clearOnThemeUnload = Fuego.onThemeUnload(() => console.log('Theme unloaded'));

// stop watching
clearOnThemeLoad();
clearOnThemeUnload();
```

### Docs

Contributions are welcome and encouraged. To get started contributing to the project, please see the [Contribution guidelines](https://github.com/fuegokit/fuegokit/blob/main/CONTRIBUTING.md). 
For support, reach out in [#design-systems](https://appfireworkspace.slack.com/archives/C03CTJZ4BUH).

Not listed items from `Fuego` object you can treat as a private API and it shouldn't be used in your production code.

| Method                                                        | Description                                                                                                         |
|---------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `loadTheme(theme)`                                            | Loads theme from a `Map<TokenName, TokenValue>` theme file. You can call it multiple times to switch between themes |
| `unloadTheme()`                                               | Remove loaded theme                                                                                                 |
| `onThemeLoad(callback)`                                       | Subscribe to theme changes. `onThemeLoad` returns a callback which you can use to stop watching.                    |
| `onThemeUnload(callback)`                                     | Subscribe to theme unload event.                                                                                    |
| `addUpdateAlias(tokenName, alias)`                            | Create token alias                                                                                                  |
| `removeAlias(alias)`                                          | Remove token alias                                                                                                  |
| `loadThemeExtension(themeExtensionMap)`                       | Load theme extensions. Use it only when built-in tokens are not enaugh.                                             |
| `unloadThemeExtension()`                                      | Unload theme extensions                                                                                             | 
| `themeGet(tokenOrAliasOrExtensionName)`                       | Get a ready to use value. These values will react automaticaly to theme changes.                                    |
| `themeGetTailwindClass(tokenName, tailwindType, prefix = '')` | Experimental. Get tailwind css class name from token name                                                           |
