design-token-management

Design Token Management

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "design-token-management" with this command: npx skills add melodic-software/claude-code-plugins/melodic-software-claude-code-plugins-design-token-management

Design Token Management

Guidance for implementing design token systems, token schemas, and multi-platform token delivery for design systems.

When to Use This Skill

  • Defining design token schemas and structures

  • Implementing CSS variable architectures

  • Building token transformation pipelines

  • Managing token naming conventions

  • Integrating with design tools (Figma, Style Dictionary)

Token Architecture

Token Hierarchy

┌─────────────────────────────────────────────────────────────────┐ │ TOKEN HIERARCHY │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ PRIMITIVE TOKENS (Raw Values) │ │ ├── colors.blue.500: #3B82F6 │ │ ├── spacing.4: 1rem │ │ └── font-size.base: 16px │ │ │ │ ▼ │ │ │ │ SEMANTIC TOKENS (Meaning/Purpose) │ │ ├── color.action.primary: {colors.blue.500} │ │ ├── spacing.component.padding: {spacing.4} │ │ └── typography.body.size: {font-size.base} │ │ │ │ ▼ │ │ │ │ COMPONENT TOKENS (Component-Specific) │ │ ├── button.primary.background: {color.action.primary} │ │ ├── card.padding: {spacing.component.padding} │ │ └── paragraph.font-size: {typography.body.size} │ │ │ └─────────────────────────────────────────────────────────────────┘

Token Schema

Core Token Model

public class DesignTokenSet { public string Name { get; set; } = string.Empty; public string Version { get; set; } = "1.0.0";

// Token categories
public ColorTokenCategory Colors { get; set; } = new();
public TypographyTokenCategory Typography { get; set; } = new();
public SpacingTokenCategory Spacing { get; set; } = new();
public BorderTokenCategory Borders { get; set; } = new();
public ShadowTokenCategory Shadows { get; set; } = new();
public AnimationTokenCategory Animation { get; set; } = new();

// Semantic mappings
public SemanticTokens Semantic { get; set; } = new();

// Component tokens
public Dictionary<string, ComponentTokens> Components { get; set; } = new();

}

public class ColorTokenCategory { // Primitive color scales public ColorScale Gray { get; set; } = new(); public ColorScale Blue { get; set; } = new(); public ColorScale Green { get; set; } = new(); public ColorScale Red { get; set; } = new(); public ColorScale Yellow { get; set; } = new(); public ColorScale Purple { get; set; } = new();

// Additional custom scales
public Dictionary<string, ColorScale> Custom { get; set; } = new();

}

public class ColorScale { public string _50 { get; set; } = string.Empty; public string _100 { get; set; } = string.Empty; public string _200 { get; set; } = string.Empty; public string _300 { get; set; } = string.Empty; public string _400 { get; set; } = string.Empty; public string _500 { get; set; } = string.Empty; public string _600 { get; set; } = string.Empty; public string _700 { get; set; } = string.Empty; public string _800 { get; set; } = string.Empty; public string _900 { get; set; } = string.Empty; public string _950 { get; set; } = string.Empty; }

public class TypographyTokenCategory { // Font families public Dictionary<string, string> FontFamily { get; set; } = new() { ["sans"] = "'Inter', system-ui, sans-serif", ["serif"] = "'Georgia', serif", ["mono"] = "'JetBrains Mono', monospace" };

// Font sizes
public Dictionary&#x3C;string, string> FontSize { get; set; } = new()
{
    ["xs"] = "0.75rem",
    ["sm"] = "0.875rem",
    ["base"] = "1rem",
    ["lg"] = "1.125rem",
    ["xl"] = "1.25rem",
    ["2xl"] = "1.5rem",
    ["3xl"] = "1.875rem",
    ["4xl"] = "2.25rem"
};

// Font weights
public Dictionary&#x3C;string, string> FontWeight { get; set; } = new()
{
    ["normal"] = "400",
    ["medium"] = "500",
    ["semibold"] = "600",
    ["bold"] = "700"
};

// Line heights
public Dictionary&#x3C;string, string> LineHeight { get; set; } = new()
{
    ["none"] = "1",
    ["tight"] = "1.25",
    ["normal"] = "1.5",
    ["relaxed"] = "1.75"
};

// Letter spacing
public Dictionary&#x3C;string, string> LetterSpacing { get; set; } = new()
{
    ["tight"] = "-0.025em",
    ["normal"] = "0",
    ["wide"] = "0.025em"
};

}

public class SpacingTokenCategory { public Dictionary<string, string> Scale { get; set; } = new() { ["0"] = "0", ["px"] = "1px", ["0.5"] = "0.125rem", ["1"] = "0.25rem", ["2"] = "0.5rem", ["3"] = "0.75rem", ["4"] = "1rem", ["5"] = "1.25rem", ["6"] = "1.5rem", ["8"] = "2rem", ["10"] = "2.5rem", ["12"] = "3rem", ["16"] = "4rem", ["20"] = "5rem", ["24"] = "6rem" }; }

public class SemanticTokens { // Action colors public SemanticColorGroup Action { get; set; } = new() { Primary = "{colors.blue.500}", PrimaryHover = "{colors.blue.600}", Secondary = "{colors.gray.500}", SecondaryHover = "{colors.gray.600}", Danger = "{colors.red.500}", DangerHover = "{colors.red.600}" };

// Feedback colors
public SemanticColorGroup Feedback { get; set; } = new()
{
    Success = "{colors.green.500}",
    Warning = "{colors.yellow.500}",
    Error = "{colors.red.500}",
    Info = "{colors.blue.500}"
};

// Surface colors
public SemanticSurfaceGroup Surface { get; set; } = new()
{
    Background = "#FFFFFF",
    Raised = "#F9FAFB",
    Overlay = "rgba(0, 0, 0, 0.5)"
};

// Text colors
public SemanticTextGroup Text { get; set; } = new()
{
    Primary = "{colors.gray.900}",
    Secondary = "{colors.gray.600}",
    Muted = "{colors.gray.400}",
    Inverse = "#FFFFFF",
    Link = "{colors.blue.500}"
};

}

Token JSON Format

Standard Token Format

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "name": "Brand Tokens", "version": "1.0.0", "colors": { "primitive": { "blue": { "50": { "value": "#EFF6FF", "type": "color" }, "100": { "value": "#DBEAFE", "type": "color" }, "500": { "value": "#3B82F6", "type": "color" }, "600": { "value": "#2563EB", "type": "color" }, "900": { "value": "#1E3A8A", "type": "color" } } }, "semantic": { "action": { "primary": { "value": "{colors.primitive.blue.500}", "type": "color", "description": "Primary action color" }, "primary-hover": { "value": "{colors.primitive.blue.600}", "type": "color" } } } }, "typography": { "font-family": { "base": { "value": "'Inter', system-ui, sans-serif", "type": "fontFamily" }, "heading": { "value": "'Inter', system-ui, sans-serif", "type": "fontFamily" } }, "font-size": { "sm": { "value": "0.875rem", "type": "fontSize" }, "base": { "value": "1rem", "type": "fontSize" }, "lg": { "value": "1.125rem", "type": "fontSize" }, "xl": { "value": "1.25rem", "type": "fontSize" } } }, "spacing": { "1": { "value": "0.25rem", "type": "spacing" }, "2": { "value": "0.5rem", "type": "spacing" }, "4": { "value": "1rem", "type": "spacing" }, "8": { "value": "2rem", "type": "spacing" } }, "components": { "button": { "primary": { "background": { "value": "{colors.semantic.action.primary}" }, "background-hover": { "value": "{colors.semantic.action.primary-hover}" }, "text": { "value": "#FFFFFF" }, "padding-x": { "value": "{spacing.4}" }, "padding-y": { "value": "{spacing.2}" }, "border-radius": { "value": "{borders.radius.md}" } } } } }

Token Transformation Pipeline

Token Processor Service

public class TokenProcessor { public async Task<Dictionary<string, string>> ResolveTokensAsync( DesignTokenSet tokenSet) { var resolved = new Dictionary<string, string>();

    // First pass: primitive tokens (no references)
    ResolvePrimitives(tokenSet, resolved);

    // Second pass: semantic tokens (reference primitives)
    ResolveSemanticTokens(tokenSet.Semantic, resolved);

    // Third pass: component tokens (reference semantic)
    foreach (var (componentName, tokens) in tokenSet.Components)
    {
        ResolveComponentTokens(componentName, tokens, resolved);
    }

    return resolved;
}

private void ResolveSemanticTokens(
    SemanticTokens semantic,
    Dictionary&#x3C;string, string> resolved)
{
    // Resolve token references like {colors.blue.500}
    foreach (var property in semantic.GetType().GetProperties())
    {
        var value = property.GetValue(semantic);
        if (value is string strValue &#x26;&#x26; strValue.StartsWith("{"))
        {
            var resolvedValue = ResolveReference(strValue, resolved);
            resolved[$"semantic.{property.Name}"] = resolvedValue;
        }
    }
}

private string ResolveReference(
    string reference,
    Dictionary&#x3C;string, string> resolved)
{
    // Extract path from {colors.blue.500}
    var path = reference.Trim('{', '}');

    if (resolved.TryGetValue(path, out var value))
    {
        return value;
    }

    throw new TokenResolutionException($"Cannot resolve token reference: {reference}");
}

}

Output Formats

CSS Variables Generator

public class CssTokenGenerator : ITokenOutputGenerator { public string Generate(Dictionary<string, string> tokens) { var sb = new StringBuilder(); sb.AppendLine(":root {");

    foreach (var (name, value) in tokens)
    {
        var cssVarName = ToCssVariableName(name);
        sb.AppendLine($"  --{cssVarName}: {value};");
    }

    sb.AppendLine("}");
    return sb.ToString();
}

private string ToCssVariableName(string tokenPath)
{
    // colors.blue.500 -> color-blue-500
    return tokenPath
        .Replace(".", "-")
        .Replace("_", "-")
        .ToLowerInvariant();
}

}

SCSS Variables Generator

public class ScssTokenGenerator : ITokenOutputGenerator { public string Generate(Dictionary<string, string> tokens) { var sb = new StringBuilder(); sb.AppendLine("// Design Tokens - Auto-generated"); sb.AppendLine();

    // Group by category
    var grouped = tokens.GroupBy(t => t.Key.Split('.')[0]);

    foreach (var group in grouped)
    {
        sb.AppendLine($"// {group.Key}");
        foreach (var (name, value) in group)
        {
            var scssVarName = ToScssVariableName(name);
            sb.AppendLine($"${scssVarName}: {value};");
        }
        sb.AppendLine();
    }

    return sb.ToString();
}

}

Tailwind Config Generator

public class TailwindTokenGenerator : ITokenOutputGenerator { public string Generate(Dictionary<string, string> tokens) { var config = new { theme = new { extend = new { colors = BuildColorConfig(tokens), spacing = BuildSpacingConfig(tokens), fontSize = BuildFontSizeConfig(tokens), fontFamily = BuildFontFamilyConfig(tokens) } } };

    return $"module.exports = {JsonSerializer.Serialize(config, new JsonSerializerOptions { WriteIndented = true })}";
}

}

Generated Tailwind Output

module.exports = { theme: { extend: { colors: { primary: { DEFAULT: 'var(--color-action-primary)', hover: 'var(--color-action-primary-hover)', }, success: 'var(--color-feedback-success)', warning: 'var(--color-feedback-warning)', error: 'var(--color-feedback-error)', }, spacing: { '1': 'var(--spacing-1)', '2': 'var(--spacing-2)', '4': 'var(--spacing-4)', '8': 'var(--spacing-8)', }, fontSize: { 'sm': 'var(--font-size-sm)', 'base': 'var(--font-size-base)', 'lg': 'var(--font-size-lg)', } } } }

Token API

REST Endpoints

GET /api/tokens # List all token sets GET /api/tokens/{id} # Get token set by ID POST /api/tokens # Create token set PUT /api/tokens/{id} # Update token set DELETE /api/tokens/{id} # Delete token set

GET /api/tokens/{id}/resolved # Get resolved (flattened) tokens GET /api/tokens/{id}/css # Get CSS variables output GET /api/tokens/{id}/scss # Get SCSS variables output GET /api/tokens/{id}/tailwind # Get Tailwind config GET /api/tokens/{id}/json # Get JSON format (for tools)

POST /api/tokens/import # Import from Figma/Style Dictionary POST /api/tokens/validate # Validate token references

Token Response

{ "data": { "id": "tokens-123", "name": "Brand Tokens v2", "version": "2.0.0", "categories": ["colors", "typography", "spacing", "shadows"], "tokenCount": 156, "outputs": { "css": "/api/tokens/tokens-123/css", "scss": "/api/tokens/tokens-123/scss", "tailwind": "/api/tokens/tokens-123/tailwind" }, "lastModified": "2025-01-15T10:30:00Z" } }

Naming Conventions

Token Naming Pattern

Category.Variant.Property.State

Examples:

  • color.action.primary.default
  • color.action.primary.hover
  • color.feedback.success
  • typography.heading.size.large
  • spacing.component.padding
  • border.radius.medium
  • shadow.elevation.low

Best Practices

Convention Good Bad

Semantic naming color.action.primary

color.blue

Consistent casing font-size-base

FontSizeBase

Hierarchical spacing.component.padding

component-padding

Descriptive color.text.muted

color.gray-400

Platform-agnostic elevation.low

box-shadow-1

Design Tool Integration

Figma Tokens Import

public class FigmaTokenImporter { public async Task<DesignTokenSet> ImportAsync(string figmaFileId) { var figmaTokens = await _figmaClient.GetTokensAsync(figmaFileId);

    return new DesignTokenSet
    {
        Name = figmaTokens.Name,
        Colors = MapFigmaColors(figmaTokens.Colors),
        Typography = MapFigmaTypography(figmaTokens.Typography),
        Spacing = MapFigmaSpacing(figmaTokens.Spacing)
    };
}

}

Style Dictionary Integration

{ "source": ["tokens/**/*.json"], "platforms": { "css": { "transformGroup": "css", "buildPath": "build/css/", "files": [{ "destination": "variables.css", "format": "css/variables" }] }, "scss": { "transformGroup": "scss", "buildPath": "build/scss/", "files": [{ "destination": "_variables.scss", "format": "scss/variables" }] } } }

Related Skills

  • multi-site-theming

  • Per-tenant theme customization

  • headless-api-design

  • Token API delivery

  • content-type-modeling

  • Token sets as content

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Coding

design-thinking

No summary provided by upstream source.

Repository SourceNeeds Review
-109
melodic-software
Coding

plantuml-syntax

No summary provided by upstream source.

Repository SourceNeeds Review
-77
melodic-software
Coding

system-prompt-engineering

No summary provided by upstream source.

Repository SourceNeeds Review
-59
melodic-software