Skip to main content

​
Tokensets

Tokensets are collections of related design tokens within a workspace. They help organize tokens by category, component, or any logical grouping that makes sense for your design system.

​
What is a Tokenset?

A tokenset is a group of design tokens that share a common purpose or category. Each tokenset belongs to a workspace and can have multiple modes (like light and dark themes).

​
Example Structure

Tokenset: "Colors"
├── Mode: "Light"
│   ├── colors.primary.500 = #3b82f6
│   └── colors.background = #ffffff
└── Mode: "Dark"
    ├── colors.primary.500 = #60a5fa
    └── colors.background = #000000

Tokenset: "Typography"
├── Mode: "Base"
    ├── font.size.body = 16px
    └── font.family.sans = "Inter"

​
Creating a Tokenset

curl -X POST https://app.tokencraft.dev/api/v1/workspaces/{workspace_id}/tokensets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Colors",
    "description": "Color tokens for the design system"
  }'

​
Tokenset Properties

PropertyTypeDescription
idstringUnique identifier
workspace_idstringParent workspace ID
namestringTokenset name
descriptionstringOptional description
created_attimestampCreation date
updated_attimestampLast update date

​
Common Tokenset Categories

​
1. Colors

All color-related tokens:
  • Brand colors
  • Semantic colors (success, error, warning)
  • Background colors
  • Text colors

​
2. Typography

Font-related tokens:
  • Font families
  • Font sizes
  • Font weights
  • Line heights
  • Letter spacing

​
3. Spacing

Layout and spacing tokens:
  • Margins
  • Padding
  • Gap values
  • Layout units

​
4. Sizing

Dimension tokens:
  • Component sizes
  • Icon sizes
  • Border widths

​
5. Effects

Visual effects:
  • Shadows
  • Border radius
  • Transitions
  • Animations

​
Multi-mode Support

Each tokenset can have multiple modes for different contexts: 
Tokenset: "Colors"
├── Light Mode
│   └── colors.background = #ffffff
├── Dark Mode
│   └── colors.background = #000000
├── High Contrast Mode
    └── colors.background = #000000
Learn more about Modes.

​
Best Practices

​
1. Logical Grouping

Group tokens by category:
  • ✅ Separate tokenset for colors, typography, spacing
  • ❌ Mixing all token types in one tokenset

​
2. Clear Naming

Use descriptive, consistent names:
  • ✅ “Core Colors”, “Typography”, “Component Spacing”
  • ❌ “Tokens1”, “TS”, “Misc”

​
3. Documentation

Add descriptions to explain purpose: 
{
  "name": "Semantic Colors",
  "description": "Context-specific colors for success, error, warning, and info states"
}

​
4. Modular Organization

Create focused tokensets:
  • ✅ Small, specific tokensets
  • ❌ One giant tokenset with everything

​
Managing Tokensets

​
Listing Tokensets

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

​
Getting a Tokenset

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

​
Updating a Tokenset

curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Colors",
    "description": "Primary brand color palette"
  }'

​
Exporting Tokensets

Export all modes of a tokenset: 
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/export?format=json"
See Export for all export options.

​
Next Steps

Modes

Learn about multi-mode support

Tokens

Understand individual tokens

API Reference

Explore tokenset endpoints

Export

Export in multiple formats