@maxio-com/design-tokens

Design Tokens

Maxio UI Design Tokens

This package is used to store and maintain design tokens for Maxio UI. Tokens exists in the form of CSS variables and are used to maintain a consistent design system across all Maxio UI components (used directly within our Design System).

JavaScript variables are used only to refer to the CSS Variables with main purpose to fuel the Tailwind Theme - you should prefer using the CSS variables directly in any other case.

The source of truth is located in Figma/Notion and is exported to this package. Learn more about the Design Tokens here.

Installation

Design tokens are distributed as an npm package. You can install them using npm, yarn, or pnpm:

pnpm install @maxio/design-tokens

To use the design tokens in your project, you can import the CSS file into your project:

@import '@maxio-com/design-tokens/variables.css';

To leverage the Tailwind Theme, you can import the config file into your project:

import { tailwindTheme } from '@maxio/design-tokens';

// your tailwind config
export default {
  ...
  theme: tailwindTheme,
  ...
};

Backward compatibility

All the changes in the design tokens should be backward compatible. This means that if you change a token, you should not break any existing components that use that token. Existing components should continue to work as expected. If you need to make a breaking change, you should create a new token and deprecate the old one.

After the deprecation period, and making sure migration has been done, you can remove the old token.

Dark mode

Semantic tokens are composed in a way that they can be used in both light and dark mode. This means that you can use the same tokens for both light and dark mode, and the tokens will automatically adjust to the mode.

We use data attribute ([data-maxio-mode="dark"]) to toggle dark mode. It allows to control the dark mode per component, and it also allows to control the dark mode globally.

.my-component {
  background-color: var(--maxio-color-bg-primary);
  color: var(--maxio-color-text-primary);
}

<!-- regular component -->
<div class="my-component">...</div>

<!-- dark mode -->
<div class="my-component" data-maxio-mode="dark">...</div>

You can nest modes (to achieve custom solutions), just use data-maxio-mode="dark/light" in your component tree.

FAQ

How do I use these tokens?

You can use these tokens by importing the CSS file into your project. You can then use the tokens in your CSS or JavaScript files.

How do I update these tokens?

You can update these tokens by modifying the CSS file in this package and submitting a PR. For more information, refer to the How to Update Semantic Tokens documentation.