@odx/design-tokens
v4.2.0
Published
ODX Design Tokens
Readme
@odx/design-tokens
The @odx/design-tokens package provides a centralized collection of design tokens for the ODX Design System. These tokens include essential design variables such as colors, spacing, typography scales, and other key visual attributes, ensuring consistency and cohesion across all ODX projects.
Features
- Design Tokens: Centralized collection of design variables for colors, spacing, typography, and more.
- CSS Variables: Exported as CSS custom properties for easy integration into your stylesheets.
- JavaScript and TypeScript Support: Available as JavaScript and TypeScript modules for seamless integration into your codebase.
Install
PNPM
pnpm add @odx/design-tokensNPM
npm i @odx/design-tokens --save Setup
Once installed, you can import the design tokens and fonts into your project:
CSS
@import "@odx/design-tokens/fonts"; /* @odx/design-tokens/assets/fonts.css */
@import "@odx/design-tokens/css"; /* @odx/design-tokens/dist/tokens.css */JavaScript
// import CSS variables
import '@odx/design-tokens/css';
// usage with JS
import { token } from '@odx/design-tokens';
/**
* @param {string} id
* @param {{ mode?: 'light' | 'dark' | 'auto', eaaConformity?: boolean }} [input] - optional
* */
token('color.background.primary.rest'); // CSS variable: var(--odx-color-background-primary-rest)
token('color.background.primary.rest', { mode: 'dark' }); // dark mode color value in hex
// Raw tokens object
import { tokens } from '@odx/design-tokens';
// JSON import (requires bundler support for JSON modules)
import tokenData from '@odx/design-tokens/tokens.json' with { type: 'json' };Note: The JSON import syntax requires a bundler that supports JSON modules (Webpack 5+, Vite, esbuild, or Node.js 20+).
Light/Dark mode support
You can manage light/dark mode using either the JavaScript API or CSS classes. The JavaScript approach is recommended for dynamic theme switching.
Using JavaScript
import { setTheme, darkModeClass, lightModeClass } from '@odx/design-tokens';
// Set theme programmatically
setTheme({ mode: 'dark' }); // applies 'odx-dark-mode' class to document.documentElement
setTheme({ mode: 'light' }); // applies 'odx-light-mode' class
setTheme({ mode: 'auto' }); // follows system preference (prefers-color-scheme)
// You can also target specific elements
const element = document.querySelector('.my-component');
setTheme({ mode: 'dark' }, element);
// Access class name constants
console.log(darkModeClass); // 'odx-dark-mode'
console.log(lightModeClass); // 'odx-light-mode'Using CSS classes
To enable dark mode styles, add the .odx-dark-mode class to an element.
<html class="odx-dark-mode">
<!-- Your content here will use dark mode styles -->
</html>To enable light mode styles, add the .odx-light-mode class to an element.
<html class="odx-light-mode">
<!-- Your content here will use light mode styles -->
</html>Without either class, the default :root styles apply and respect the system's prefers-color-scheme preference.
European Accessibility Act (EAA) Conformity
EAA conformity mode overrides the
palette.cyan.*color tokens (including the "Dräger Air Blue" color) to meet WCAG 2.1 AA contrast requirements.
Using JavaScript
import { setTheme, eaaConformityClass } from '@odx/design-tokens';
// Enable EAA conformity
setTheme({ eaaConformity: true }); // applies 'odx-eaa-compliant' class
// Target specific elements
const element = document.querySelector('.my-component');
setTheme({ eaaConformity: true }, element);
// Combine with theme setting
setTheme({ mode: 'dark', eaaConformity: true });
// Access class name constant
console.log(eaaConformityClass); // 'odx-eaa-compliant'Using CSS classes
To enable EAA compliant colors, add the .odx-eaa-compliant class to an element.
<html class="odx-eaa-compliant">
<!-- Your content here will use EAA compliant colors -->
</html>The
.odx-eaa-compliantclass can be combined with the dark and light mode classes but must be added to the same element.
<html class="odx-dark-mode odx-eaa-compliant">
<!-- Dark mode with EAA compliance -->
</html>Documentation
For detailed documentation on how to use the @odx/design-tokens package, including examples and best practices, please visit our documentation.