Export Mode

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

This /api/v1 endpoint exports raw mode data and does not resolve organization environment releases. For environment-targeted exports, use: /api/organizations/{orgId}/environments/{environmentId}/export.

Endpoint

GET /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

curl -H "Authorization: Bearer tkc_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 "actions@github.com"
          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

Documentation Index

​Export Mode

​Endpoint

​Request

​Path Parameters

​Query Parameters

​Supported Formats

​Response Examples

​JSON Format (W3C)

​CSS Format

​iOS Format (Swift)

​Android Format (XML)

​Examples

​JavaScript Example

​Python Example

​Error Responses

​400 Bad Request

​404 Not Found

​Use Cases

​1. Web Development

​2. React/Next.js

​3. iOS Development

​4. Android Development

​5. CI/CD Integration

​Token Resolution

​Best Practices

​1. Separate Files by Mode

​2. Automate Syncing

​3. Version Control

​4. Add Comments

​Next Steps

GitHub Actions

JavaScript Integration

List Modes

Export Tokenset

Export Mode

Endpoint

Request

Path Parameters

Query Parameters

Supported Formats

Response Examples

JSON Format (W3C)

CSS Format

iOS Format (Swift)

Android Format (XML)

Examples

JavaScript Example

Python Example

Error Responses

400 Bad Request

404 Not Found

Use Cases

1. Web Development

2. React/Next.js

3. iOS Development

4. Android Development

5. CI/CD Integration

Token Resolution

Best Practices

1. Separate Files by Mode

2. Automate Syncing

3. Version Control

4. Add Comments

Next Steps