Tokens & Themes
Jux provides a system for managing design tokens and themes, allowing you to create consistent and flexible designs across your application. This guide will show you how to set up tokens and themes in your Jux configuration and how to use them in your project.
Configuring Design Tokens
Design tokens are a platform-agnostic way to define your design system and ensure consistency across your application. It’s key-value pairs that define the visual properties of your application, such as colors, typography, spacing, and more.
Token Structure
Tokens can be nested to any depth, allowing for a hierarchical organization of your design tokens. Each token can have the following properties:
$value
: The actual value of the token. This can be any valid CSS value or an object for composite tokens.$description
: A description of the token (optional).
Core Tokens
Core tokens are the foundation of your design system. They define the basic design elements that are shared across all themes.
Core tokens are defined in the core_tokens
section of your jux.config
file:
CSS Output
Jux automatically converts your design tokens into CSS custom properties, making them easy to use in your styles. The name of the CSS custom property is derived from the token’s path in the design token object. All core token variables are prefixed with --core
to distinguish them from theme-specific variables.
For example, the core tokens defined above will be converted to the following CSS variables:
Themes
Themes in Jux allow you to create multiple variations of your design system, such as light and dark modes, while leveraging your core tokens.
Themes are defined in the themes section of your jux.config.ts
file. Here’s an example configuration that builds upon our previous core tokens setup:
To apply a theme to your application, you need to add the data-theme
attribute to your HTML. Here’s an example of how to do this and how to switch themes:
CSS Output
Jux generates CSS for themes by wrapping theme-specific styles with the appropriate data attribute selector. This allows for easy theme switching using CSS selectors.
Using Tokens in Your Styles
Jux provides multiple ways to use tokens in your styles, from direct references to utility-based approaches.
To use tokens in your styles, wrap the token name with curly braces {}
. Jux will replace these with the corresponding CSS custom property at build time.
During development, if you use a non-existent token, Jux will display a warning in the console, making it easy to catch typos and errors.
Single-Value / Composite Tokens
In Jux, tokens can be defined in two primary ways: as single-value tokens or composite tokens. Understanding the difference between these types is crucial for effectively managing your design system and applying styles.
Single-value tokens
Single-value tokens contain one specific value and are typically used for individual CSS properties.
When you use a single-value token in your styles, Jux converts it to a CSS custom property (variable) syntax:
will be converted to:
Composite tokens
Composite tokens are collections of related values, often used for complex styles like typography or shadows.
When you use a composite token, Jux merges its values directly into the final CSS:
Will be processed to:
Token Types
Jux provides a set of predefined token types to help you categorize and structure your design tokens effectively. Each token type is designed to handle specific aspects of your design system. This guide will walk you through each type, providing explanations and examples.
Color
Description
The color
token type is used for defining all color values in your design system.
Example
Dimension
Description
The dimension
token type is used for sizes, spacing, and any other measurement values.
Example
FontFamily
Description
The fontFamily
token type defines the font families used in your design system.
Example
FontWeight
Description
The fontWeight
token type defines the various font weights used in your typography.
Example
Duration
Description
The duration
token type is used for defining timing values, often used in animations and transitions.
Example
CubicBezier
Description
The cubicBezier
token type defines easing functions for animations and transitions.
Example
Number
Description
The number
token type is used for unitless numeric values.
Example
StrokeStyle
Description
The strokeStyle
token type is used to define styles for strokes, often used in SVGs or borders.
Example
Border
Description
The border
token type is used to define complete border styles.
Example
Transition
Description
The transition
token type defines complete transition properties.
Example
Shadow
Description
The shadow
token type is used to define box shadows and text shadows.
Example
Gradient
Description
The gradient
token type defines gradient styles.
Example
Typography
Description
The typography
token type is used to define complete typography styles.
Example
FontStyle
Description
The fontStyle
token type defines font styles such as italic or normal.
Example
TextDecoration
Description
The textDecoration
token type defines text decoration styles.
Example
TypeScript Support
Both css
and styled
functions in Jux are fully typed, providing several benefits:
- Autocomplete suggestions for token paths
- Type checking to prevent usage of non-existent tokens
- IntelliSense support for exploring available tokens
Refer to the TypeScript Guide for more information on TypeScript support in Jux.