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

# Tokensets

> Group related tokens together

# 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

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

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

## 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](/concepts/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:

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

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

### Getting a Tokenset

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

### Updating a Tokenset

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

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

See [Export](/api-reference/export/tokenset) for all export options.

## Next Steps

<CardGroup cols={2}>
  <Card title="Modes" icon="moon" href="/concepts/modes">
    Learn about multi-mode support
  </Card>

  <Card title="Tokens" icon="circle" href="/concepts/tokens">
    Understand individual tokens
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tokensets/get">
    Explore tokenset endpoints
  </Card>

  <Card title="Export" icon="file-export" href="/api-reference/export/mode">
    Export in multiple formats
  </Card>
</CardGroup>