Export Mode

Export a specific mode in various formats

Export Mode

Exports tokens from a specific mode in your chosen format. This is the most commonly used export endpoint.

Endpoint

GET /api/v1/tokensets/{id}/modes/{modeId}/export?format={format}

Request

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Tokenset ID
modeId	string	Yes	Mode ID

Query Parameters

Parameter	Type	Required	Description
format	string	No	Export format (default: json)

Supported Formats

Format	Description	Use Case
json	W3C Design Tokens	Universal, framework-agnostic
css	CSS Custom Properties	Web projects
ios	Swift UIColor/CGFloat	iOS apps
android	XML Resources	Android apps

Response Examples

JSON Format (W3C)

Content-Type: application/json

{
  "colors": {
    "primary": {
      "500": {
        "value": "#3b82f6",
        "type": "color",
        "description": "Primary brand color"
      }
    },
    "background": {
      "default": {
        "value": "#ffffff",
        "type": "color"
      }
    }
  },
  "spacing": {
    "base": {
      "value": "16px",
      "type": "dimension"
    }
  }
}

CSS Format

Content-Type: text/css

:root {
  /* Primary brand color */
  --colors-primary-500: #3b82f6;
  --colors-background-default: #ffffff;
  --spacing-base: 16px;
}

iOS Format (Swift)

Content-Type: text/plain

import UIKit

// Design Tokens
// Generated by Tokencraft API

enum DesignTokens {
    enum Color {
        /// Primary brand color
        static let colorsPrimary500 = UIColor(red: 0.231, green: 0.510, blue: 0.965, alpha: 1.000)
        static let colorsBackgroundDefault = UIColor(red: 1.000, green: 1.000, blue: 1.000, alpha: 1.000)
    }
    
    enum Dimension {
        static let spacingBase: CGFloat = 16.0
    }
}

Android Format (XML)

Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<!-- Design Tokens -->
<!-- Generated by Tokencraft API -->
<resources>
    <!-- Primary brand color -->
    <color name="colors-primary-500">#3b82f6</color>
    <color name="colors-background-default">#ffffff</color>
    <dimen name="spacing-base">16dp</dimen>
</resources>

Examples

JSON

curl -H "Authorization: Bearer dtk_your_token_here" \
  "https://app.tokencraft.dev/api/v1/tokensets/tokenset-123/modes/mode-light/export?format=json" \
  -o tokens-light.json

JavaScript Example

async function exportMode(tokensetId, modeId, format = 'json') {
  const response = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/export?format=${format}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TOKENCRAFT_TOKEN}`
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Export failed: ${response.statusText}`);
  }
  
  return format === 'json' ? await response.json() : await response.text();
}

// Usage
const lightTokens = await exportMode('tokenset-123', 'mode-light', 'json');
const darkCss = await exportMode('tokenset-123', 'mode-dark', 'css');

Python Example

import requests

def export_mode(tokenset_id, mode_id, format='json'):
    response = requests.get(
        f'https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/export',
        params={'format': format},
        headers={'Authorization': f'Bearer {token}'}
    )
    
    response.raise_for_status()
    
    return response.json() if format == 'json' else response.text

# Usage
light_tokens = export_mode('tokenset-123', 'mode-light', 'json')
dark_css = export_mode('tokenset-123', 'mode-dark', 'css')

Error Responses

400 Bad Request

{
  "error": "Invalid format. Supported formats: json, css, ios, android"
}

404 Not Found

{
  "error": "Mode not found"
}

Use Cases

1. Web Development

Import CSS variables:

# Download light and dark themes
curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/tokensets/$TOKENSET_ID/modes/light/export?format=css" \
  -o src/tokens-light.css

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/tokensets/$TOKENSET_ID/modes/dark/export?format=css" \
  -o src/tokens-dark.css

/* In your main CSS */
@import './tokens-light.css';

@media (prefers-color-scheme: dark) {
  @import './tokens-dark.css';
}

2. React/Next.js

Fetch at build time:

// scripts/fetch-tokens.js
const fs = require('fs');

async function fetchTokens() {
  const light = await exportMode('tokenset-123', 'mode-light', 'json');
  const dark = await exportMode('tokenset-123', 'mode-dark', 'json');
  
  fs.writeFileSync('src/tokens/light.json', JSON.stringify(light, null, 2));
  fs.writeFileSync('src/tokens/dark.json', JSON.stringify(dark, null, 2));
}

fetchTokens();

// package.json
{
  "scripts": {
    "prebuild": "node scripts/fetch-tokens.js",
    "build": "next build"
  }
}

3. iOS Development

Add to Xcode project:

#!/bin/bash
# scripts/sync-tokens.sh

curl -H "Authorization: Bearer $TOKENCRAFT_TOKEN" \
  "$API_BASE/tokensets/$TOKENSET_ID/modes/light/export?format=ios" \
  -o ios/DesignTokens.swift

// Usage in your app
import UIKit

class MyView: UIView {
    override func layoutSubviews() {
        super.layoutSubviews()
        backgroundColor = DesignTokens.Color.colorsBackgroundDefault
    }
}

4. Android Development

Add to res/values:

#!/bin/bash
curl -H "Authorization: Bearer $TOKENCRAFT_TOKEN" \
  "$API_BASE/tokensets/$TOKENSET_ID/modes/light/export?format=android" \
  -o android/app/src/main/res/values/tokens.xml

curl -H "Authorization: Bearer $TOKENCRAFT_TOKEN" \
  "$API_BASE/tokensets/$TOKENSET_ID/modes/dark/export?format=android" \
  -o android/app/src/main/res/values-night/tokens.xml

<!-- Usage in layouts -->
<TextView
    android:textColor="@color/colors-text-primary"
    android:padding="@dimen/spacing-base" />

5. CI/CD Integration

GitHub Actions example:

name: Sync Design Tokens

on:
  schedule:
    - cron: '0 0 * * *'  # Daily
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Download Light Mode
        run: |
          curl -H "Authorization: Bearer ${{ secrets.TOKENCRAFT_TOKEN }}" \
            "${{ secrets.API_BASE }}/tokensets/${{ secrets.TOKENSET_ID }}/modes/light/export?format=css" \
            -o src/tokens-light.css
      
      - name: Download Dark Mode
        run: |
          curl -H "Authorization: Bearer ${{ secrets.TOKENCRAFT_TOKEN }}" \
            "${{ secrets.API_BASE }}/tokensets/${{ secrets.TOKENSET_ID }}/modes/dark/export?format=css" \
            -o src/tokens-dark.css
      
      - name: Commit changes
        run: |
          git config user.name "GitHub Actions"
          git config user.email "[e-mail]"
          git add src/tokens-*.css
          git diff --staged --quiet || git commit -m "Update design tokens"
          git push

Token Resolution

Aliases are automatically resolved in exports:

// Your tokens
{
  "colors.primary.500": "#3b82f6",
  "colors.button.primary": { "alias_to": "colors.primary.500" }
}

// Exported (CSS)
:root {
  --colors-primary-500: #3b82f6;
  --colors-button-primary: #3b82f6;  /* Resolved */
}

Best Practices

1. Separate Files by Mode

Keep themes in separate files:

tokens-light.css
tokens-dark.css
tokens-high-contrast.css

2. Automate Syncing

Don’t manually download tokens:

{
  "scripts": {
    "sync-tokens": "node scripts/sync-tokens.js",
    "prebuild": "npm run sync-tokens"
  }
}

3. Version Control

Commit generated files:

# .gitignore
# Don't ignore generated tokens
!src/tokens/*.css
!src/tokens/*.json

4. Add Comments

Include metadata in exports:

/* Design Tokens - Light Mode */
/* Last updated: 2025-01-15 */
/* Source: https://app.tokencraft.dev */
:root {
  --colors-primary-500: #3b82f6;
}

Next Steps

GitHub Actions

Automate token syncing

JavaScript Integration

Use tokens in your app

List Modes

Get all available modes

Export Tokenset

Export all modes at once