@sandlada/material-token-generator
Version:
Use the @material/material-color-utilities tool to create a set of tokens based on material design.
246 lines (206 loc) • 6.87 kB
Markdown
# @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());
````