# @sandlada/material-token-generator

_If you find any problems, please report them._

This project uses the [@material/material-color-utilities](https://github.com/material-foundation/material-color-utilities) open source project to convert the results generated by @material/material-color-utilities into CSS styles.

- ESM Supported Only
- Typescript Supported

```
npm i @sandlada/material-tokens-generator @material/material-color-utilities
```

```javascript
import {
    EMaterialContrastLevel,
    EMaterialVariant,
    MaterialTokens,
} from "@sandlada/material-tokens-generator";

const theme = new MaterialTokens(Hct.from(140, 90, 50), {
    contrastLevel: EMaterialContrastLevel.Default,
    variant: EMaterialVariant.Fidelity,
    isDark: false,
    prefix: "my-prefix",
    excludedTokens: [
        "surfaceTint",
    ],
});
```

## Usage

### Generate Colors

For example:

````javascript
import { MaterialTokens } from "@sandlada/material-tokens-generator";

const theme = new MaterialTokens(Hct.from(140, 90, 50), {
    isDark: false,
});

/**
 * @output
 * ```
 * --md-sys-color-primary-palette-key-color: #278900;
 * --md-sys-color-secondary-palette-key-color: #578245;
 * ...
 * --md-sys-color-on-tertiary-fixed: #001e2b;
 * --md-sys-color-on-tertiary-fixed-variant: #004d67;
 * ```
 */
console.log(theme.cssText());
````

### Generate Palettes

For example:

````javascript
import { MaterialPalettes } from "@sandlada/material-tokens-generator";

const palettes = new MaterialPalettes(Hct.from(120, 90, 70), {
    isDark: true,
});

/**
 * @output
 * ```
 * --md-sys-palette-primary-0: #000000;
 * --md-sys-palette-secondary-0: #000000;
 * ...
 * --md-sys-palette-neutral-100: #ffffff;
 * --md-sys-palette-neutralVariant-100: #ffffff;
 * ```
 */
console.log(palettes.cssText());
````

## API

| Classes                                       |                                                  Features |
| :-------------------------------------------- | --------------------------------------------------------: |
| `MaterialTokens`, `MaterialDynamicTokens`     |      Used to create tokens like `--md-sys-color-primary`. |
| `MaterialPalettes`, `MaterialDynamicPalettes` | Used to create tokens like `--md-sys-palette-primary-40`. |

### constructor

| Param          | Option                | Type                                          | Required |
| :------------- | :-------------------- | :-------------------------------------------- | -------: |
| sourceColorHct |                       | `string`                                      |      Yes |
| options        | isDark                | `boolean`                                     |       No |
| options        | variant               | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8`   |       No |
| options        | contrastLevel         | `-1.0 \| 0 \| 0.5 \| 1.0`                     |       No |
| options        | prefix                | `string`                                      |       No |
| options        | excludedTokens        | `Array<keyof TMaterialColors>`                |       No |
| options        | customTokens          | `Record<keyof TMaterialColors, DynamicColor>` |       No |
| options        | primaryPalette        | `TonalPalette`                                |       No |
| options        | secondaryPalette      | `TonalPalette`                                |       No |
| options        | tertiaryPalette       | `TonalPalette`                                |       No |
| options        | neutralPalette        | `TonalPalette`                                |       No |
| options        | neutralVariantPalette | `TonalPalette`                                |       No |
| options        | levels                | `Array<number>`                               |       No |

```javascript
new MaterialTokens(Hct.from(140, 90, 50));
new MaterialTokens(Hct.from(140, 90, 50), {
    prefix: "my-color",
    variant: EMaterialVariant.Content,
    isDark: true,
    contrastLevel: 0,
    excludedTokens: ["surfaceTint"],
});

new MaterialPalettes(Hct.from(75, 90, 75));
new MaterialPalettes(Hct.from(75, 90, 75), {
    contrastLevel: 0,
    isDark: false,
    levels: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
    prefix: "my-palette",
    variant: EMaterialVariant.Rainbow,
});

new MaterialDynamicPalettes({});
new MaterialDynamicPalettes({
    sourceColorHct: Hct.from(75, 90, 75),
    contrastLevel: 0,
    isDark: false,
    levels: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
    prefix: "my-palette",
    variant: EMaterialVariant.Rainbow,
    primaryPalette: TonalPalette.fromHueAndChroma(200, 75),
    secondaryPalette: TonalPalette.fromHueAndChroma(120, 75),
    tertiaryPalette: TonalPalette.fromHueAndChroma(140, 75),
    neutralPalette: TonalPalette.fromHueAndChroma(180, 25),
    neutralVariantPalette: TonalPalette.fromHueAndChroma(200, 35),
});
```

### tokens

````javascript
const theme = new MaterialTokens(Hct.from(140, 90, 50));
const tokens = theme.tokens();
/**
 * @output
 * ```
 * {
 *      background: "#f5fcec",
 *      error: "#ba1a1a",
 *      ...
 *      tertiaryFixedDim: "#77d1fe",
 *      tertiaryPaletteKeyColor: "#0080a9",
 * }
 * ```
 */
console.log(tokens);

/**
 * @output
 * #f5fcec
 */
console.log(tokens.surface);
````

### cssPropertyRecord

````javascript
const theme = new MaterialTokens(Hct.from(140, 90, 50));

/**
 * @output
 * ```
 * {
 *      background: {
 *          "name": "--md-sys-color-background",
 *          "value": {
 *              "name": "--md-sys-color-background",
 *              "initialValue": "#f5fcec",
 *              "inherits": false,
 *           "syntax": "<color>"
 *           }
 *      }
 *      ...
 * }
 * ```
 */
console.log(theme.cssPropertyRecord());
````

### cssPropertyText

````javascript
const theme = new MaterialTokens(Hct.from(140, 90, 50));

/**
 * @output
 * ```
 * @property --md-sys-color-primary-palette-key-color { initial-value: #278900; syntax: <color>; inherits: false; }
 * ...
 * @property --md-sys-color-on-tertiary-fixed-variant { initial-value: #004d67; syntax: <color>; inherits: false; }
 * ```
 */
console.log(theme.cssPropertyText());
````

### cssRecord

````javascript
const theme = new MaterialTokens(Hct.from(140, 90, 50));

/**
 * @output
 * ```
 * {
 *      background: {
 *          "name": "--md-sys-color-background",
 *          "value": "#f5fcec"
 *      },
 *      ...
 * }
 * ...
 * @property --md-sys-color-on-tertiary-fixed-variant { initial-value: #004d67; syntax: <color>; inherits: false; }
 * ```
 */
console.log(theme.cssRecord());
````

### cssText

````javascript
const theme = new MaterialTokens(Hct.from(140, 90, 50));

/**
 * @output
 * ```
 * --md-sys-color-primary-palette-key-color: #278900;
 * ...
 * --md-sys-color-on-tertiary-fixed-variant: #004d67;
 * ```
 */
console.log(theme.cssText());
````