Skip to main content

​
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
}

​
Font Size

{
  "name": "font.size.body",
  "type": "fontSize",
  "value": "16px"
}

​
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

PropertyTypeDescription
idstringUnique identifier
tokenset_idstringParent tokenset ID
mode_idstringMode this token belongs to
namestringToken name (e.g., colors.primary.500)
typestringToken type (color, dimension, etc.)
valueanyToken value
descriptionstringOptional description
alias_tostringReference to another token (for aliases)
created_attimestampCreation date
updated_attimestampLast 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

  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

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

​
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