> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokencraft.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Modes

> Create theme variations with modes

# 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

```json theme={null}
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**

```json theme={null}
Light: colors.background = #ffffff
Dark:  colors.background = #000000
```

**High Contrast Mode**

```json theme={null}
High Contrast: colors.primary = #0000ff
```

### 2. Platform Variants

**Web vs Mobile**

```json theme={null}
Web:    spacing.base = 16px
Mobile: spacing.base = 12px
```

### 3. Brand Variations

**Primary and Secondary Brands**

```json theme={null}
Brand A: colors.primary = #3b82f6
Brand B: colors.primary = #10b981
```

### 4. Contextual Variations

**Marketing vs Product**

```json theme={null}
Marketing: font.family.heading = "Playfair Display"
Product:   font.family.heading = "Inter"
```

## Creating Modes

<CodeGroup>
  ```bash API theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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
      })
    }
  );
  ```
</CodeGroup>

## 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:

```javascript theme={null}
// 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

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

### Getting Tokens for a Mode

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

### Exporting a Specific Mode

```bash theme={null}
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:

<CodeGroup>
  ```css Light Mode (CSS) theme={null}
  /* Light mode tokens */
  :root {
    --colors-background: #ffffff;
    --colors-text: #000000;
    --colors-primary: #3b82f6;
  }
  ```

  ```css Dark Mode (CSS) theme={null}
  /* Dark mode tokens */
  :root {
    --colors-background: #000000;
    --colors-text: #ffffff;
    --colors-primary: #60a5fa;
  }
  ```
</CodeGroup>

## Implementation Example

### React with Theme Switching

```jsx theme={null}
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

```css theme={null}
/* 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

```bash theme={null}
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

```bash theme={null}
curl -X DELETE https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id} \
  -H "Authorization: Bearer YOUR_TOKEN"
```

<Warning>
  You cannot delete the default mode. Set another mode as default first.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Tokens" icon="circle" href="/concepts/tokens">
    Learn about individual tokens
  </Card>

  <Card title="Export Modes" icon="file-export" href="/api-reference/export/mode">
    Export mode-specific tokens
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tokensets/modes">
    Mode API endpoints
  </Card>
</CardGroup>