diff --git a/README.md b/README.md index 1f3cd7d..dbbf24d 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,39 @@ # Design Tokens -The Open Inwoner project 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 +The Open Inwoner Platform (OIP) project 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 - -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. - -The draft [Design Token Format](https://design-tokens.github.io/community-group/format/) drives the -structure of these design tokens. +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`. -## Add this as a submodule +Long term goal is to make it possible for different municipalities to make their own design-tokens +and then simply switch themes in OIP. -In the root folder of your project, create a dir or directly add the submodule in its own directory: +## How it works -```bash -cd open-inwoner-design-tokens +The design tokens are specified 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 CSS variables files, SASS vars... to be consumed in downstream projects. -git submodule add git@github.com:maykinmedia/open-inwoner-design-tokens.git +The draft [Design Token Format](https://design-tokens.github.io/community-group/format/) drives the structure of these design tokens. -git status +**Using tokens** -git submodule update --init -``` +If you are only _consuming_ the design tokens, the easiest integration path is adding the +NPM-package in your own project. -Do not forget to commit these changes to your repository. +## Add this package to your project -If you are using Github actions, add these to your script: +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. The easiest integration path is adding the NPM package as dependency to your project: ```bash - - uses: actions/checkout@v3 - with: - submodules: 'true' +npm install --save-dev @open-inwoner/design-tokens ``` +This gets the node module from https://www.npmjs.com/package/@open-inwoner/design-tokens ## Usage @@ -54,27 +49,24 @@ 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. - -```bash -git submodule update --remote --merge -``` +Import the CSS in your own CSS files by using our theme class in your Master HTML template -**Using tokens** +```HTML -If you are only _consuming_ the design tokens, the easiest integration path is adding this -package in your own project. + +``` -Then, import the desired build target artifact and run your usual build chain. +```css +.openinwoner-theme { + ... +} +``` -**Developing and using tokens** +## Developing and using tokens -If you actively need to add or change 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. +In case you do not just wish to consume, but add completely new tokens or adjust their values, 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. -This allows you to create atomic PRs with design token changes, while being able to develop against -the newest changes. +This allows you to create atomic PRs with design token changes, while being able to develop against the newest changes. Run: @@ -101,7 +93,9 @@ tokens. E.g. if you have two tokens definition files like: { "oip": { "color": { - "fg": {"value": "#000000"} + "fg": { + "value": "#000000" + } } } } @@ -112,7 +106,9 @@ tokens. E.g. if you have two tokens definition files like: "oip": { "color": { "fg": { - "muted": {"value": "#000000"} + "muted": { + "value": "#000000" + } } } } @@ -137,10 +133,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 + +From the root folder of your project: + +```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..00f22ad 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.5", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@open-inwoner/design-tokens", - "version": "0.0.1", + "version": "0.0.5-alpha.5", "license": "EUPL-1.2", "devDependencies": { "chokidar": "^3.5.3", diff --git a/package.json b/package.json index 4e88c57..2356e0f 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.5", "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..5e3e75f 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" - } - } + "value": "#949494", + "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..7bbbbea --- /dev/null +++ b/src/community/utrecht/paragraph.tokens.json @@ -0,0 +1,22 @@ +{ + "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"}, + "font-size": {"value": "14px"}, + "line-height": {"value": "20px"}, + "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..40c0a7d --- /dev/null +++ b/src/components/paragraph-modifiers.tokens.json @@ -0,0 +1,16 @@ +{ + "oip": { + "utrecht-paragraph": { + "muted": { + "color": {"value": "{oip.color.fg-muted}"} + }, + "centered": { + "text-align": {"value": "center"} + }, + "compact": { + "margin-bottom": {"value": "0 !important"}, + "margin-top": {"value": "0 !important"} + } + } + } +}