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

const response = await fetch(
  `https://app.tokencraft.dev/api/v1/workspaces/${workspaceId}/tokensets`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Colors',
      description: 'Color tokens for the design system'
    })
  }
);

Tokenset Properties

Property	Type	Description
`id`	string	Unique identifier
`workspace_id`	string	Parent workspace ID
`name`	string	Tokenset name
`description`	string	Optional description
`created_at`	timestamp	Creation date
`updated_at`	timestamp	Last 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

​Tokensets

​What is a Tokenset?

​Example Structure

​Creating a Tokenset

​Tokenset Properties

​Common Tokenset Categories

​1. Colors

​2. Typography

​3. Spacing

​4. Sizing

​5. Effects

​Multi-mode Support

​Best Practices

​1. Logical Grouping

​2. Clear Naming

​3. Documentation

​4. Modular Organization

​Managing Tokensets

​Listing Tokensets

​Getting a Tokenset

​Updating a Tokenset

​Exporting Tokensets

​Next Steps