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

{
  "name": "colors.primary.500",
  "type": "color",
  "value": "#3b82f6",
  "description": "Primary brand color"
}

Token Types

Tokencraft supports all W3C Design Token types:

Color

{
  "name": "colors.primary.500",
  "type": "color",
  "value": "#3b82f6"
}

Dimension

{
  "name": "spacing.base",
  "type": "dimension",
  "value": "16px"
}

Font Family

{
  "name": "font.family.sans",
  "type": "fontFamily",
  "value": ["Inter", "sans-serif"]
}

Font Weight

{
  "name": "font.weight.bold",
  "type": "fontWeight",
  "value": 700
}

Duration

{
  "name": "transition.fast",
  "type": "duration",
  "value": "150ms"
}

Cubic Bezier

{
  "name": "easing.ease-out",
  "type": "cubicBezier",
  "value": [0, 0, 0.2, 1]
}

Shadow

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

Border

{
  "name": "border.default",
  "type": "border",
  "value": {
    "width": "1px",
    "style": "solid",
    "color": "#e5e7eb"
  }
}

Typography

{
  "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:

{
  "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

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

Creating Tokens

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

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'
    })
  }
);

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

# 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

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

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

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:

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

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

JavaScript/TypeScript

import tokens from './tokens.json';

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

React Native

import tokens from './tokens.json';

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

Next Steps

Export Formats

Export tokens in various formats

API Reference

Explore token endpoints

Integrations

Use tokens in your projects

​Tokens

​What is a Token?

​Example

​Token Types

​Color

​Dimension

​Font Family

​Font Weight

​Font Size

​Duration

​Cubic Bezier

​Shadow

​Border

​Typography

​Token Properties

​Naming Convention

​Examples

​Best Practices

​Token Aliases

​Benefits of Aliases

​Creating Tokens

​Token Organization

​By Category

​By Component

​By Scale

​Working with Tokens

​Listing Tokens

​Getting a Specific Token

​Updating a Token

​Deleting a Token

​Token Resolution

​Using Tokens in Code

​CSS Variables

​JavaScript/TypeScript

​React Native

​Next Steps