diff --git a/README.md b/README.md index 1f3cd7d..040278b 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,34 @@ # Design Tokens -The Open Inwoner project has the goal to follow the +The Open Inwoner Project (OIP) has the goal to follow the [NL Design System](https://github.com/nl-design-system). We organize the design tokens in JSON files and use them within the Open Inwoner backend project. -## How it works +For any component that OIP has that corresponds with a community component, we use the community +classes. But for any component that OIP has that does not have an NLDS equivalent, we use our own +OIP brand tokens. We also set OIP (brand/component) tokens in case we have certain values that are +used repeatedly, like for example `border-radius`. -Specify the design tokens in JSON files, which are picked up and merged using the -[style-dictionary](https://www.npmjs.com/package/style-dictionary) library. The resulting packages -include various build targets, such as ES6 modules, CSS variables files, SASS vars... to be consumed -in downstream projects. +Long term goal is to make it possible for different municipalities to make their own design-tokens +and then simply switch themes in OIP. -The draft [Design Token Format](https://design-tokens.github.io/community-group/format/) drives the -structure of these design tokens. - -## Add this as a submodule - -In the root folder of your project, create a dir or directly add the submodule in its own directory: - -```bash -cd open-inwoner-design-tokens - -git submodule add git@github.com:maykinmedia/open-inwoner-design-tokens.git +**Using tokens** -git status +If you are only _consuming_ the design tokens, the easiest integration path is adding the +NPM-package in your own project. -git submodule update --init -``` +## Add this package to your project -Do not forget to commit these changes to your repository. +This package can be added to your project as an NPM node module: after building the node, you will +only need to work with its rendered CSS. -If you are using Github actions, add these to your script: +Get the node module from https://www.npmjs.com/package/@open-inwoner/design-tokens ```bash - - uses: actions/checkout@v3 - with: - submodules: 'true' +npm i @open-inwoner/design-tokens ``` - ## Usage Install the necessary modules (from inside the `open-inwoner-design-tokens` directory): @@ -54,22 +43,33 @@ Generate the CSS files npm run build ``` -In order to update an existing Git submodule, you need to execute the “git submodule update” with the “–remote” and the “–merge” option. +Import the CSS in your own CSS files by using our theme class in your Master HTML template -```bash -git submodule update --remote --merge +```HTML + + ``` -**Using tokens** +```css +.openinwoner-theme { +. . . +} +``` -If you are only _consuming_ the design tokens, the easiest integration path is adding this -package in your own project. +## Developing and using tokens -Then, import the desired build target artifact and run your usual build chain. +In case you do not just wish to consume, but add completely new tokens or adjust their values, +follow these steps. Then, import the desired build target artifact and run your usual build chain. + +Specify the design tokens in JSON files, which are picked up and merged using the +[style-dictionary](https://www.npmjs.com/package/style-dictionary) library. The resulting packages +include various build targets, such as ES6 modules, CSS variables files, SASS vars... to be consumed +in downstream projects. -**Developing and using tokens** +The draft [Design Token Format](https://design-tokens.github.io/community-group/format/) drives the +structure of these design tokens. -If you actively need to add or change design tokens, we recommend installing the package locally and +For adding or changing design tokens, we recommend installing the package locally and using npm workspaces or `npm link` for the least-friction experience. You can include the package as a git-submodule and leverage npm workspaces with instructions in the downstream projects. @@ -101,7 +101,9 @@ tokens. E.g. if you have two tokens definition files like: { "oip": { "color": { - "fg": {"value": "#000000"} + "fg": { + "value": "#000000" + } } } } @@ -112,7 +114,9 @@ tokens. E.g. if you have two tokens definition files like: "oip": { "color": { "fg": { - "muted": {"value": "#000000"} + "muted": { + "value": "#000000" + } } } } @@ -137,10 +141,43 @@ e.g.: { "oip": { "color": { - "fg-muted": {"value": "#000000"} + "fg-muted": { + "value": "#000000" + } } } } ``` The latter form is harder to keep track off across files though. + +### Add as a submodule instead of NPM + +In the root folder of your project, create a dir or directly add the submodule in its own directory: + +```bash +cd open-inwoner-design-tokens + +git submodule add git@github.com:maykinmedia/open-inwoner-design-tokens.git + +git status + +git submodule update --init +``` + +Do not forget to commit these changes to your repository. + +If you are using Github actions, add these to your script: + +```bash + - uses: actions/checkout@v3 + with: + submodules: 'true' +``` + +In order to update an existing Git submodule, you need to execute the “git submodule update” with +the “–remote” and the “–merge” option. + +```bash +git submodule update --remote --merge +``` diff --git a/package-lock.json b/package-lock.json index 29a4786..621409b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@open-inwoner/design-tokens", - "version": "0.0.1", + "version": "0.0.5-alpha.4", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@open-inwoner/design-tokens", - "version": "0.0.1", + "version": "0.0.5-alpha.4", "license": "EUPL-1.2", "devDependencies": { "chokidar": "^3.5.3", diff --git a/package.json b/package.json index 4e88c57..b353d6d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@open-inwoner/design-tokens", - "version": "0.0.3-alpha.0", + "version": "0.0.5-alpha.4", "description": "Design tokens for Open Inwoner", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", diff --git a/src/brand/openinwoner/color.tokens.json b/src/brand/openinwoner/color.tokens.json index 24ed63c..9ac5c25 100644 --- a/src/brand/openinwoner/color.tokens.json +++ b/src/brand/openinwoner/color.tokens.json @@ -59,101 +59,43 @@ }, "success": { "value": "#4A7746", - "comment": "The dark green text color for success states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The dark green text color for success states and/or messages." }, "success-light": { "value": "#ecf4ec", - "comment": "The light green background color for success states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The light green background color for success states and/or messages." }, "warning": { "value": "#704000", - "comment": "The dark orange text color for warning states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The dark orange text color for warning states and/or messages." }, "warning-light": { "value": "#ffdcad", - "comment": "The light orange background color for warning states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The light orange background color for warning states and/or messages." }, "danger": { "value": "#5c000f", - "comment": "The dark red text color for error/critical states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The dark red text color for error/critical states and/or messages." }, "danger-light": { "value": "#ffdbe1", - "comment": "The light red background color for error/critical states and/or messages.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "The light red background color for error/critical states and/or messages." }, "bg": { "value": "#ffffff", - "comment": "Background color for the (main) user interface.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "Background color for the (main) user interface." }, "fg": { "value": "#4b4b4b", - "comment": "Blackish foreground color for the (main) user interface.", - "$extensions": { - "dte.metadata": { - "isCurated": true, - "category": "color" - } - } + "comment": "Blackish foreground color for the (main) user interface." }, "fg-muted": { "value": "#d2d2d2", - "comment": "Font/foreground color for non-actionable or less-important content.", - "$extensions": { - "dte.metadata": { - "category": "color" - } - } + "comment": "Font/foreground color for non-actionable or less-important content." }, "fg-heading": { "value": "#000000", - "comment": "Black foreground color for fully black elements.", - "$extensions": { - "dte.metadata": { - "category": "color" - } - } + "comment": "Black foreground color for fully black elements." }, "border": { "value": "#d2d2d2", @@ -167,11 +109,9 @@ }, "border": {} }, - "read-only": { - "bg": { - "value": "#d2d2d2", - "comment": "Default color for disabled/non-interactable input elements." - } + "red-notification": { + "value": "#d94100", + "comment": "The bright red color for notification badges and texts." } } } diff --git a/src/brand/openinwoner/typography.tokens.json b/src/brand/openinwoner/typography.tokens.json index 5806f10..bc181fc 100644 --- a/src/brand/openinwoner/typography.tokens.json +++ b/src/brand/openinwoner/typography.tokens.json @@ -4,9 +4,6 @@ "fg": {"value": "{oip.color.fg}"}, "font-family": {"value": "Heading"} }, - "utrecht-link": { - "font-family": {"value": "{oip.typography.sans-serif.font-family}"} - }, "text": { "margin": {"value": "20px"}, "font-size": {"value": "16px"}, diff --git a/src/community/utrecht/heading-1.tokens.json b/src/community/utrecht/heading-1.tokens.json deleted file mode 100644 index 7ae7e4c..0000000 --- a/src/community/utrecht/heading-1.tokens.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "utrecht": { - "heading-1": { - "color": {"value": "{oip.color.fg-heading}"}, - "font-family": {"value": "{oip.typography.heading.font-family}"}, - "font-size": {"value": "32px"}, - "font-weight": {"value": "bold"}, - "line-height": {"value": "41px"}, - "margin-block-end": {"value": "0"}, - "margin-block-start": {"value": "40px"} - } - } -} diff --git a/src/community/utrecht/heading-2.tokens.json b/src/community/utrecht/heading-2.tokens.json deleted file mode 100644 index b6a5daf..0000000 --- a/src/community/utrecht/heading-2.tokens.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "utrecht": { - "heading-2": { - "color": {"value": "{oip.color.fg-heading}"}, - "font-family": {"value": "{oip.typography.heading.font-family}"}, - "font-size": {"value": "24px"}, - "font-weight": {"value": "bold"}, - "letter-spacing": {"value": "normal"}, - "line-height": {"value": "34px"}, - "margin-block-end": {"value": "0"}, - "margin-block-start": {"value": "0"} - } - } -} diff --git a/src/community/utrecht/heading-3.tokens.json b/src/community/utrecht/heading-3.tokens.json deleted file mode 100644 index 0b79f03..0000000 --- a/src/community/utrecht/heading-3.tokens.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "utrecht": { - "heading-3": { - "color": {"value": "{oip.color.fg-heading}"}, - "font-family": {"value": "{oip.typography.heading.font-family}"}, - "font-size": {"value": "20px"}, - "font-weight": {"value": "bold"}, - "line-height": {"value": "30px"}, - "margin-block-end": {"value": "0"}, - "margin-block-start": {"value": "0"} - } - } -} diff --git a/src/community/utrecht/heading-4.tokens.json b/src/community/utrecht/heading-4.tokens.json deleted file mode 100644 index 18f875d..0000000 --- a/src/community/utrecht/heading-4.tokens.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "utrecht": { - "heading-4": { - "color": {"value": "{oip.color.fg-heading}"}, - "font-family": {"value": "{oip.typography.heading.font-family}"}, - "font-size": {"value": "16px"}, - "font-weight": {"value": "bold"}, - "line-height": {"value": "26px"}, - "margin-block-end": {"value": "0"}, - "margin-block-start": {"value": "0"} - } - } -} diff --git a/src/community/utrecht/heading.tokens.json b/src/community/utrecht/heading.tokens.json new file mode 100644 index 0000000..990d591 --- /dev/null +++ b/src/community/utrecht/heading.tokens.json @@ -0,0 +1,48 @@ +{ + "utrecht": { + "heading": { + "color": {"value": "{oip.color.fg-heading}"}, + "font-family": {"value": "{oip.typography.heading.font-family}"}, + "font-weight": {"value": "bold"}, + "margin-block-end": {"value": "0"}, + "margin-block-start": {"value": "0"} + }, + "heading-1": { + "color": {"value": "{oip.color.fg-heading}"}, + "font-family": {"value": "{oip.typography.heading.font-family}"}, + "font-size": {"value": "32px"}, + "font-weight": {"value": "bold"}, + "line-height": {"value": "41px"}, + "margin-block-end": {"value": "0"}, + "margin-block-start": {"value": "40px"} + }, + "heading-2": { + "color": {"value": "{oip.color.fg-heading}"}, + "font-family": {"value": "{oip.typography.heading.font-family}"}, + "font-size": {"value": "24px"}, + "font-weight": {"value": "bold"}, + "letter-spacing": {"value": "normal"}, + "line-height": {"value": "34px"}, + "margin-block-end": {"value": "0"}, + "margin-block-start": {"value": "0"} + }, + "heading-3": { + "color": {"value": "{oip.color.fg-heading}"}, + "font-family": {"value": "{oip.typography.heading.font-family}"}, + "font-size": {"value": "20px"}, + "font-weight": {"value": "bold"}, + "line-height": {"value": "30px"}, + "margin-block-end": {"value": "0"}, + "margin-block-start": {"value": "0"} + }, + "heading-4": { + "color": {"value": "{oip.color.fg-heading}"}, + "font-family": {"value": "{oip.typography.heading.font-family}"}, + "font-size": {"value": "16px"}, + "font-weight": {"value": "bold"}, + "line-height": {"value": "26px"}, + "margin-block-end": {"value": "0"}, + "margin-block-start": {"value": "0"} + } + } +} diff --git a/src/community/utrecht/paragraph.tokens.json b/src/community/utrecht/paragraph.tokens.json new file mode 100644 index 0000000..4a66573 --- /dev/null +++ b/src/community/utrecht/paragraph.tokens.json @@ -0,0 +1,50 @@ +{ + "utrecht": { + "paragraph": { + "color": { + "value": "{oip.color.fg}" + }, + "font-family": { + "value": "{oip.typography.sans-serif.font-family}" + }, + "font-size": { + "value": "{oip.text.font-size}" + }, + "font-weight": { + "value": "normal" + }, + "line-height": { + "value": "24px" + }, + "margin-block-end": { + "value": "0" + }, + "margin-block-start": { + "value": "0" + }, + "small": { + "color": { + "value": "rgba(75,75,75,0.9)" + }, + "font-family": { + "value": "{oip.typography.sans-serif.font-family}" + }, + "font-weight": { + "value": "normal" + }, + "line-height": { + "value": "20px" + }, + "font-size": { + "value": "14px" + }, + "margin-block-end": { + "value": "0" + }, + "margin-block-start": { + "value": "0" + } + } + } + } +} diff --git a/src/community/utrecht/typography.tokens.json b/src/community/utrecht/typography.tokens.json index 3d394dc..cdcbe59 100644 --- a/src/community/utrecht/typography.tokens.json +++ b/src/community/utrecht/typography.tokens.json @@ -4,6 +4,17 @@ "font-family": { "value": "{oip.typography.sans-serif.font-family}", "comment": "The body font-style for the theme." + }, + "font-size": { + "value": "16px", + "comment": "The body font-size for the theme." + }, + "color": { + "value": "#4b4b4b" + }, + "line-height": { + "value": "24px", + "comment": "Default body line-height." } } } diff --git a/src/components/paragraph-modifiers.tokens.json b/src/components/paragraph-modifiers.tokens.json new file mode 100644 index 0000000..5721c7a --- /dev/null +++ b/src/components/paragraph-modifiers.tokens.json @@ -0,0 +1,26 @@ +{ + "oip": { + "utrecht": { + "paragraph": { + "small": { + "font-size": { + "value": "14px" + }, + "line-height": { + "value": "{utrecht.paragraph.small.line-height}" + } + }, + "muted": { + "color": { + "value": "{oip.color.fg-muted}" + } + }, + "centered": { + "text-align": { + "value": "center" + } + } + } + } + } +}