design-token-management

What this skill does

# 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

```text
┌─────────────────────────────────────────────────────────────────┐
│                       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

```csharp
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<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<string, string> FontWeight { get; set; } = new()
    {
        ["normal"] = "400",
        ["medium"] = "500",
        ["semibold"] = "600",
        ["bold"] = "700"
    };

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

    // Letter spacing
    public Dictionary<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

```json
{
  "$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": { "valu