Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[✨]: Add common tokens #11

Merged
merged 4 commits into from
Apr 16, 2024
Merged

[✨]: Add common tokens #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e8b510
Update dev theming
mimshins Apr 16, 2024
ed98022
Add shallow merge util
mimshins Apr 16, 2024
62b5ae0
Update documentation
mimshins Apr 16, 2024
8b169e3
Add common tokens
mimshins Apr 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
244 changes: 144 additions & 100 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,25 @@ The library exposes two APIs, `create` and `defaultCSSVariableGenerator`:
### 1. `create`

```ts
declare const create: (variants, config?) => {
declare const create: (tokens, config?) => {
VariantSelector,
useTokens,
generateCSSVariablesAsInlineStyle,
}
```

This is the main API exposed by the library. It will take your variants map and an optional config options to create your theming client.
This is the main API exposed by the library. It will take your tokens and an optional config options to create your theming client.

The `tokens` param expects to have `variants` and `common` tokens provided.

```ts
const tokens = {
variants: {/* The variant tokens map */},
common: {/* Tokens that are common and non-variant */}
}
```

> Please note that we shallow-merge tokens of a selected variant with common tokens to generate the result tokens. (Merging order: `{ ...variantTokens, ...commonTokens }`)<br />Common tokens can therefore potentially override variant tokens. Make sure they don't have any intersected keys.

The `config` options are:

Expand All @@ -61,10 +72,16 @@ A wrapper component which will activate a variant for the tree it's wrapping. Th

A React hook to use in a component that is descendant of `<VariantSelector>` wrapper. It returns the tokens of the selected variant.

#### `generateCSSVariablesAsInlineStyle(variant)`:
#### `generateCSSVariablesAsInlineStyle(variant, options?)`:

A helper function to generate CSS variables in valid CSS syntax (`--variable=value`). It is helpful when you want to manually control the population of the CSS variables (e.g. Put initial tokens on html tag with `<html style={generateCSSVariablesAsInlineStyle('dark')} />`)

The `options` are:

| Property Name | Type | Default | Description |
|---------------|------|---------|-------------|
| disableCommonTokensGeneration | `boolean` | `false` | If `true`, Common tokens CSS variable generation will be disabled. |

### 2. `defaultCSSVariableGenerator`

```ts
Expand Down Expand Up @@ -132,63 +149,74 @@ To getting started, all you need to do is:
```ts
// theming.ts

const variants = {
dark: {
colors: {
primary: {
base: "d1",
hover: "d2",
active: "d3",
disabled: "d4",
},
secondary: {
base: "d5",
hover: "d6",
active: "d7",
disabled: "d8",
},
neutral: {
text: {
base: "d9",
secondary: "d10",
tertiary: "d11",
const tokens = {
variants: {
dark: {
colors: {
primary: {
base: "d1",
hover: "d2",
active: "d3",
disabled: "d4",
},
secondary: {
base: "d5",
hover: "d6",
active: "d7",
disabled: "d8",
},
background: {
base: "d12",
container: "d13",
elevated: "d14",
neutral: {
text: {
base: "d9",
secondary: "d10",
tertiary: "d11",
},
background: {
base: "d12",
container: "d13",
elevated: "d14",
},
},
},
},
},
light: {
colors: {
primary: {
base: "l1",
hover: "l2",
active: "l3",
disabled: "l4",
},
secondary: {
base: "l5",
hover: "l6",
active: "l7",
disabled: "l8",
},
neutral: {
text: {
base: "l9",
secondary: "l10",
tertiary: "l11",
light: {
colors: {
primary: {
base: "l1",
hover: "l2",
active: "l3",
disabled: "l4",
},
background: {
base: "l12",
container: "l13",
elevated: "l14",
secondary: {
base: "l5",
hover: "l6",
active: "l7",
disabled: "l8",
},
neutral: {
text: {
base: "l9",
secondary: "l10",
tertiary: "l11",
},
background: {
base: "l12",
container: "l13",
elevated: "l14",
},
},
},
},
},
common: {
typefaces: {
monospace: "c1",
rtl: "c2",
ltr: "c3",
decorative: "c4",
},
space: "c5",
}
};
```

Expand All @@ -199,66 +227,77 @@ const variants = {

import { create } from "react-design-tokens";

const variants = {
dark: {
colors: {
primary: {
base: "d1",
hover: "d2",
active: "d3",
disabled: "d4",
},
secondary: {
base: "d5",
hover: "d6",
active: "d7",
disabled: "d8",
},
neutral: {
text: {
base: "d9",
secondary: "d10",
tertiary: "d11",
const tokens = {
variants: {
dark: {
colors: {
primary: {
base: "d1",
hover: "d2",
active: "d3",
disabled: "d4",
},
background: {
base: "d12",
container: "d13",
elevated: "d14",
secondary: {
base: "d5",
hover: "d6",
active: "d7",
disabled: "d8",
},
neutral: {
text: {
base: "d9",
secondary: "d10",
tertiary: "d11",
},
background: {
base: "d12",
container: "d13",
elevated: "d14",
},
},
},
},
},
light: {
colors: {
primary: {
base: "l1",
hover: "l2",
active: "l3",
disabled: "l4",
},
secondary: {
base: "l5",
hover: "l6",
active: "l7",
disabled: "l8",
},
neutral: {
text: {
base: "l9",
secondary: "l10",
tertiary: "l11",
light: {
colors: {
primary: {
base: "l1",
hover: "l2",
active: "l3",
disabled: "l4",
},
background: {
base: "l12",
container: "l13",
elevated: "l14",
secondary: {
base: "l5",
hover: "l6",
active: "l7",
disabled: "l8",
},
neutral: {
text: {
base: "l9",
secondary: "l10",
tertiary: "l11",
},
background: {
base: "l12",
container: "l13",
elevated: "l14",
},
},
},
},
},
common: {
typefaces: {
monospace: "c1",
rtl: "c2",
ltr: "c3",
decorative: "c4",
},
space: "c5",
}
};

export const { useTokens, VariantSelector, generateCSSVariablesAsInlineStyle } = create(variants);
export const { useTokens, VariantSelector, generateCSSVariablesAsInlineStyle } = create(tokens);
```

3. Use the theme variants:
Expand Down Expand Up @@ -305,6 +344,11 @@ The CSS variables generated for this variants map with default configuration set
--colors-neutral-background-base: d12;
--colors-neutral-background-container: d13;
--colors-neutral-background-elevated: d14;
--typefaces-monospace: c1;
--typefaces-rtl: c2;
--typefaces-ltr: c3;
--typefaces-decorative: c4;
--space: c5;
```

## Contributing
Expand Down
Loading
Loading