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
  }'

const response = await fetch(
  `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Dark',
      is_default: false
    })
  }
);

Mode Properties

Property	Type	Description
`id`	string	Unique identifier
`tokenset_id`	string	Parent tokenset ID
`name`	string	Mode name
`is_default`	boolean	Whether this is the default mode
`created_at`	timestamp	Creation date
`updated_at`	timestamp	Last 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;
}

/* Dark mode tokens */
:root {
  --colors-background: #000000;
  --colors-text: #ffffff;
  --colors-primary: #60a5fa;
}

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

​Modes

​What is a Mode?

​Example

​Common Use Cases

​1. Theme Variations

​2. Platform Variants

​3. Brand Variations

​4. Contextual Variations

​Creating Modes

​Mode Properties

​Default Mode

​Token Values Across Modes

​Best Practices

​1. Consistent Token Names

​2. Complete Coverage

​3. Semantic Naming

​4. Default Mode Selection

​Working with Modes

​Listing Modes

​Getting Tokens for a Mode

​Exporting a Specific Mode

​Mode-Specific Exports

​Implementation Example

​React with Theme Switching

​CSS with Media Query

​Managing Modes

​Updating a Mode

​Deleting a Mode

​Next Steps

Tokens

Export Modes

API Reference

Modes

What is a Mode?

Example

Common Use Cases

1. Theme Variations

2. Platform Variants

3. Brand Variations

4. Contextual Variations

Creating Modes

Mode Properties

Default Mode

Token Values Across Modes

Best Practices

1. Consistent Token Names

2. Complete Coverage

3. Semantic Naming

4. Default Mode Selection

Working with Modes

Listing Modes

Getting Tokens for a Mode

Exporting a Specific Mode

Mode-Specific Exports

Implementation Example

React with Theme Switching

CSS with Media Query

Managing Modes

Updating a Mode

Deleting a Mode

Next Steps