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

# Tokens

> The building blocks of your design system

# Tokens

Design tokens are the atomic values in your design system. They represent visual design decisions as data, making them easy to share, maintain, and apply across platforms.

## What is a Token?

A design token is a named entity that stores a visual design attribute. Instead of hard-coding values like `#3b82f6` or `16px` throughout your code, you reference them by name like `colors.primary.500` or `spacing.base`.

### Example

```json theme={null}
{
  "name": "colors.primary.500",
  "type": "color",
  "value": "#3b82f6",
  "description": "Primary brand color"
}
```

## Token Types

Tokencraft supports all W3C Design Token types:

### Color

```json theme={null}
{
  "name": "colors.primary.500",
  "type": "color",
  "value": "#3b82f6"
}
```

### Dimension

```json theme={null}
{
  "name": "spacing.base",
  "type": "dimension",
  "value": "16px"
}
```

### Font Family

```json theme={null}
{
  "name": "font.family.sans",
  "type": "fontFamily",
  "value": ["Inter", "sans-serif"]
}
```

### Font Weight

```json theme={null}
{
  "name": "font.weight.bold",
  "type": "fontWeight",
  "value": 700
}
```

### Font Size

```json theme={null}
{
  "name": "font.size.body",
  "type": "fontSize",
  "value": "16px"
}
```

### Duration

```json theme={null}
{
  "name": "transition.fast",
  "type": "duration",
  "value": "150ms"
}
```

### Cubic Bezier

```json theme={null}
{
  "name": "easing.ease-out",
  "type": "cubicBezier",
  "value": [0, 0, 0.2, 1]
}
```

### Shadow

```json theme={null}
{
  "name": "shadow.md",
  "type": "shadow",
  "value": {
    "offsetX": "0px",
    "offsetY": "4px",
    "blur": "6px",
    "spread": "0px",
    "color": "rgba(0, 0, 0, 0.1)"
  }
}
```

### Border

```json theme={null}
{
  "name": "border.default",
  "type": "border",
  "value": {
    "width": "1px",
    "style": "solid",
    "color": "#e5e7eb"
  }
}
```

### Typography

```json theme={null}
{
  "name": "typography.body",
  "type": "typography",
  "value": {
    "fontFamily": "Inter",
    "fontSize": "16px",
    "fontWeight": 400,
    "lineHeight": 1.5
  }
}
```

## Token Properties

| Property      | Type      | Description                              |
| ------------- | --------- | ---------------------------------------- |
| `id`          | string    | Unique identifier                        |
| `tokenset_id` | string    | Parent tokenset ID                       |
| `mode_id`     | string    | Mode this token belongs to               |
| `name`        | string    | Token name (e.g., `colors.primary.500`)  |
| `type`        | string    | Token type (color, dimension, etc.)      |
| `value`       | any       | Token value                              |
| `description` | string    | Optional description                     |
| `alias_to`    | string    | Reference to another token (for aliases) |
| `created_at`  | timestamp | Creation date                            |
| `updated_at`  | timestamp | Last update date                         |

## Naming Convention

Tokencraft uses dot notation for hierarchical organization:

```
category.subcategory.property.variant
```

### Examples

```
colors.primary.500
colors.background.default
spacing.component.padding.x
font.size.heading.h1
shadow.elevation.3
```

### Best Practices

✅ **Good:**

* `colors.primary.500`
* `spacing.base`
* `font.size.body`

❌ **Bad:**

* `primaryColor500`
* `spacing_base`
* `fontSizeBody`

## Token Aliases

Tokens can reference other tokens using aliases:

```json theme={null}
{
  "name": "colors.button.primary",
  "type": "color",
  "alias_to": "colors.primary.500",
  "value": null
}
```

When resolved, `colors.button.primary` will have the value of `colors.primary.500`.

### Benefits of Aliases

1. **Semantic meaning**: `colors.button.primary` is more meaningful than `colors.primary.500`
2. **Easy updates**: Change one value, update all references
3. **Consistency**: Ensure related tokens stay in sync

## Creating Tokens

<CodeGroup>
  ```bash API theme={null}
  curl -X POST https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "colors.primary.500",
      "type": "color",
      "value": "#3b82f6",
      "description": "Primary brand color"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.tokencraft.dev/api/v1/tokensets/${tokensetId}/modes/${modeId}/tokens`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'colors.primary.500',
        type: 'color',
        value: '#3b82f6',
        description: 'Primary brand color'
      })
    }
  );
  ```
</CodeGroup>

## Token Organization

### By Category

Group related tokens:

```
colors.primary.*
colors.secondary.*
colors.semantic.success.*
colors.semantic.error.*
```

### By Component

Organize by UI component:

```
button.background.primary
button.background.secondary
button.text.primary
button.border.default
```

### By Scale

Use numeric scales for consistency:

```
spacing.1 = 4px
spacing.2 = 8px
spacing.3 = 12px
spacing.4 = 16px
```

## Working with Tokens

### Listing Tokens

```bash theme={null}
# All tokens in a mode
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens
```

### Getting a Specific Token

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

### Updating a Token

```bash theme={null}
curl -X PATCH https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens/colors.primary.500 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "#2563eb",
    "description": "Updated primary brand color"
  }'
```

### Deleting a Token

```bash theme={null}
curl -X DELETE https://app.tokencraft.dev/api/v1/tokensets/{tokenset_id}/modes/{mode_id}/tokens/colors.primary.500 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Token Resolution

Tokencraft automatically resolves token aliases:

```json theme={null}
// Raw tokens
{
  "colors.primary.500": {
    "value": "#3b82f6",
    "type": "color"
  },
  "colors.button.primary": {
    "alias_to": "colors.primary.500",
    "type": "color"
  }
}

// Resolved
{
  "colors.primary.500": {
    "value": "#3b82f6",
    "type": "color"
  },
  "colors.button.primary": {
    "value": "#3b82f6",  // Resolved from alias
    "type": "color",
    "alias_to": "colors.primary.500"
  }
}
```

## Using Tokens in Code

### CSS Variables

```css theme={null}
.button {
  background-color: var(--colors-primary-500);
  padding: var(--spacing-base);
  font-size: var(--font-size-body);
}
```

### JavaScript/TypeScript

```javascript theme={null}
import tokens from './tokens.json';

const Button = styled.button`
  background-color: ${tokens.colors.primary['500'].value};
  padding: ${tokens.spacing.base.value};
`;
```

### React Native

```javascript theme={null}
import tokens from './tokens.json';

const styles = StyleSheet.create({
  button: {
    backgroundColor: tokens.colors.primary['500'].value,
    padding: parseInt(tokens.spacing.base.value),
  }
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Export Formats" icon="file-export" href="/api-reference/export/mode">
    Export tokens in various formats
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/tokens/list">
    Explore token endpoints
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/javascript">
    Use tokens in your projects
  </Card>
</CardGroup>