@justeat/pie-design-tokens

v7.10.1

Published

4 days ago

Design Tokens for the PIE Component System

Downloads

4,582

How to contribute:

Pre-flight

Setup environment:

yarn @ ^1.0.0
node @ ^16.0.0

Install the project:

yarn install

Build the project:

yarn build

If you need to add, change or remove tokens the changes should be done in pie-design-tokens.jsonc file, where all the tokens are stored. To verify that the changes took effect, build the project and check the compiled files in the dist folder.

Each change needs to be accompanied by manual changelog entry in CHANGELOG.md and package version bump in package.json. The package follows semantic versioning.

Each change should also be replicated in metadata/tokensMetadata.json file.

yarn test and yarn test:output -u have to be run to verify any update.

If your change touches the tokens structure, compile scripts in the build folder might need to be updated to make sure that the tokens are compiled as expected.

Pull requests

When raising a merge request in the pie-design-tokens repo, please follow these guidelines.

PR title

PR titles should start with the package version number. To mark the ticket as wip, please raise it as a Draft PR on Github.

PR Descriptions

You can copy the changelog entry into the PR description.

Things to do before requesting PR reviews

Make sure that the build ran successfully and all the PR checks passed.
Add all the details for your change to the PR description and Changelog. Use previous PRs in the repo as an example.

Dark Mode Token Support

The PIE Design Tokens now provide dark mode support through a set of html data attributes and media query rules.

How Dark Mode Tokens Work

The compiled CSS and SCSS files include two sets of dark mode rules:

Data Attribute Rule (Primary) - Triggered by HTML data-color-mode="dark" data attribute.
Media Query Fallback - Applied when there is no data-color-mode="dark" data attribute present, system preferences are set to dark mode and a data-darkmode-system data attribute is present on the html element.

CSS Selector Logic

The generated CSS uses the following selector hierarchy:

/* Primary: Explicit dark mode activation */
html[data-color-mode="dark"] {
    --dt-color-background-default: var(--dt-color-truffle-100);
    /* ... other dark mode tokens ... */
}

/* Fallback: System preference with no explicit override */
@media (prefers-color-scheme: dark) {
    html[data-darkmode-system]:not([data-color-mode]) {
        --dt-color-background-default: var(--dt-color-truffle-100);
        /* ... other dark mode tokens ... */
    }
}

Implementation Examples

Manual Dark Mode Control

<!-- Force dark mode -->
<html data-color-mode="dark">

Automatic System Preference

<!-- Respect system preference, no manual override -->
<html data-darkmode-system>

Token Categories Affected

Dark mode tokens are available for:

Colors: Background, border, content, interactive states
Elevation: Box shadows with dark theme variants
Gradients

Browser Support

Data Attributes: Supported in all modern browsers
Media Queries: prefers-color-scheme supported in all modern browsers (IE not supported)
Fallback: Light theme is the default when no conditions are met

Publishing to npm

Publishing to npm is handled automatically via GitHub Actions, as defined in the .github/workflows/build.yml file.

Manual Trigger: Publishing is performed when the workflow is triggered manually using workflow_dispatch in GitHub Actions.
Branch Selection: When manually triggering the publish workflow, make sure to select the branch you want to publish from (e.g., master).
Note: Regular pushes and pull requests do not trigger publishing. Only a manual workflow dispatch will publish the package to npm.

For more details, see the build.yml file in the .github/workflows directory.