npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@open-inwoner/design-tokens

v0.0.7-alpha.2

Published

Design tokens for Open Inwoner

Downloads

2,363

Readme

Design Tokens

The Open Inwoner Platform (OIP) project has the goal to follow the NL Design System. We organize the design tokens in JSON files and use them within the Open Inwoner backend project.

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.

Long term goal is to make it possible for different municipalities to make their own design-tokens and then simply switch themes in OIP.

How it works

The design tokens are specified in JSON files, which are picked up and merged using the style-dictionary library. The resulting packages include various build targets, such as CSS variables files, SASS vars... to be consumed in downstream projects.

The draft Design Token Format drives the structure of these design tokens.

Using tokens

If you are only consuming the design tokens, the easiest integration path is adding the NPM-package in your own project.

Add this package to your project

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:

npm install --save-dev @open-inwoner/design-tokens

This gets the node module from https://www.npmjs.com/package/@open-inwoner/design-tokens

Usage

Install the necessary modules (from inside the open-inwoner-design-tokens directory):

npm ci --legacy-peer-deps

Generate the CSS files

npm run build

Import the CSS in your own CSS files by using our theme class in your Master HTML template


<html lang="nl" class="view openinwoner-theme">
.openinwoner-theme {
  ...
}

Developing and using tokens

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.

Run:

npm start

to start the watcher which will re-build on changes.

To prettify files:

Run:

npm run format

Naming pattern

Because of the way style-dictionary works, you have to pay close attention to the structure of the tokens. E.g. if you have two tokens definition files like:

{
  "oip": {
    "color": {
      "fg": {
        "value": "#000000"
      }
    }
  }
}
{
  "oip": {
    "color": {
      "fg": {
        "muted": {
          "value": "#000000"
        }
      }
    }
  }
}

Then only --oip-color-fg will be emitted since the merged object sees a value key at the oip.color.fg path.

You can usually avoid this by sticking to a structure adhering to:

<prefix>.<component>.<modifier>.<UIState>.<CSSProperty>

Where UIState can be blank or a value like hover, active...

Alternatively, if the structure is not that important, you can put the tokens on the same level, e.g.:

{
  "oip": {
    "color": {
      "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:

cd open-inwoner-design-tokens

git submodule add [email protected]: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:

      - 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.

git submodule update --remote --merge