Skip to main content

​
Modes

Modes allow you to create variations of your design tokens within a tokenset. The most common use case is light and dark themes, but modes can represent any contextual variation.

​
What is a Mode?

A mode is a variation or theme within a tokenset. Each mode contains different values for the same token names, allowing you to maintain multiple versions of your design system.

​
Example

Tokenset: "Colors"

Mode: "Light"
{
  "colors.background": "#ffffff",
  "colors.text": "#000000",
  "colors.primary": "#3b82f6"
}

Mode: "Dark"
{
  "colors.background": "#000000",
  "colors.text": "#ffffff",
  "colors.primary": "#60a5fa"
}

​
Common Use Cases

​
1. Theme Variations

Light and Dark Modes 
Light: colors.background = #ffffff
Dark:  colors.background = #000000
High Contrast Mode 
High Contrast: colors.primary = #0000ff

​
2. Platform Variants

Web vs Mobile 
Web:    spacing.base = 16px
Mobile: spacing.base = 12px

​
3. Brand Variations

Primary and Secondary Brands 
Brand A: colors.primary = #3b82f6
Brand B: colors.primary = #10b981

​
4. Contextual Variations

Marketing vs Product 
Marketing: font.family.heading = "Playfair Display"
Product:   font.family.heading = "Inter"

​
Creating Modes

curl -X POST https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dark",
    "is_default": false
  }'

​
Mode Properties

PropertyTypeDescription
idstringUnique identifier
tokenset_idstringParent tokenset ID
namestringMode name
is_defaultbooleanWhether this is the default mode
created_attimestampCreation date
updated_attimestampLast update date

​
Default Mode

Each tokenset has one default mode. When you create a tokenset, a “Base” mode is created automatically as the default. The default mode is used:
  • As the fallback when no mode is specified
  • As the reference for other modes
  • When exporting without specifying a mode

​
Token Values Across Modes

The same token can have different values in different modes: 
// Token: colors.primary.500

// Light mode
{
  "name": "colors.primary.500",
  "mode_id": "light-mode-id",
  "value": "#3b82f6"
}

// Dark mode
{
  "name": "colors.primary.500",
  "mode_id": "dark-mode-id",
  "value": "#60a5fa"
}

​
Best Practices

​
1. Consistent Token Names

Use the same token names across all modes: ✅ Good: 
Light: colors.background
Dark:  colors.background
❌ Bad: 
Light: colors.background
Dark:  colors.background.dark

​
2. Complete Coverage

Ensure all tokens exist in all modes: ✅ All modes have colors.primary ❌ Some modes missing colors.primary

​
3. Semantic Naming

Name modes clearly:
  • ✅ “Light”, “Dark”, “High Contrast”
  • ❌ “Mode1”, “Mode2”, “Alt”

​
4. Default Mode Selection

Choose the most commonly used mode as default:
  • ✅ “Light” as default (if light theme is primary)
  • ✅ “Base” as default (for platform-agnostic tokens)

​
Working with Modes

​
Listing Modes

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes

​
Getting Tokens for a Mode

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens

​
Exporting a Specific Mode

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/export?format=css"

​
Mode-Specific Exports

When exporting, you can target specific modes: 
/* Light mode tokens */
:root {
  --colors-background: #ffffff;
  --colors-text: #000000;
  --colors-primary: #3b82f6;
}

​
Implementation Example

​
React with Theme Switching

import lightTokens from './tokens-light.json';
import darkTokens from './tokens-dark.json';

function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');
  const tokens = theme === 'light' ? lightTokens : darkTokens;
  
  return (
    <ThemeContext.Provider value={{ theme, tokens, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

​
CSS with Media Query

/* Light mode (default) */
:root {
  --colors-background: #ffffff;
  --colors-text: #000000;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --colors-background: #000000;
    --colors-text: #ffffff;
  }
}

​
Managing Modes

​
Updating a Mode

curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dark Mode",
    "is_default": false
  }'

​
Deleting a Mode

curl -X DELETE https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id} \
  -H "Authorization: Bearer YOUR_TOKEN"
You cannot delete the default mode. Set another mode as default first.

​
Next Steps

Tokens

Learn about individual tokens

Export Modes

Export mode-specific tokens

API Reference

Mode API endpoints