Design System Management

Comprehensive design token management for maintaining consistency between design files and code.

Overview

This skill provides tools for managing design system tokens throughout their lifecycle, from extraction to code generation, with support for versioning, conflict detection, and multi-platform export.

This skill covers:

• Token CRUD operations (create, read, update, delete)
• Multi-format export (JSON, Swift, CSS, Tailwind, Flutter)
• Version tracking and change history
• Design-to-code synchronization
• Conflict detection and resolution

This skill does NOT cover:

• Initial token extraction (see design-tokens-extraction skill)
• Component code generation (see design-to-* skills)

Quick Reference

Token Operations

Operation	Command	Description
List	/sync-design-system --list	Show all tokens
Add	Token CRUD workflow	Add new token
Update	Token CRUD workflow	Modify token value
Delete	Token CRUD workflow	Remove token
Export	/sync-design-system --target <path>	Export to code

Export Formats

Format	File Extension	Target
W3C JSON	.tokens.json	Platform-agnostic
Swift	.swift	iOS/macOS
CSS	.css	Web (custom properties)
Tailwind	tailwind.config.js	Tailwind CSS
Flutter	.dart	Flutter/Dart

Workflow: Token Management

Step 1: Initialize Token Store

Create or locate the design tokens file:

tokens/
├── design-tokens.json      # W3C format (source of truth)
├── generated/
│   ├── Theme.swift         # iOS/macOS output
│   ├── theme.css           # Web output
│   └── tailwind.config.js  # Tailwind output
└── .tokens-history/        # Version history

Step 2: Token CRUD Operations

Create Token:

{
  "operation": "create",
  "path": "color.semantic.error",
  "value": {
    "$value": "#DC2626",
    "$type": "color",
    "$description": "Error state color for destructive actions"
  }
}

Read Token:

{
  "operation": "read",
  "path": "color.semantic.error"
}
// Returns full token definition with metadata

Update Token:

{
  "operation": "update",
  "path": "color.semantic.error",
  "value": {
    "$value": "#EF4444"
  },
  "reason": "Improved contrast ratio"
}

Delete Token:

{
  "operation": "delete",
  "path": "color.deprecated.oldRed",
  "reason": "Replaced by color.semantic.error"
}

Step 3: Version Tracking

Track changes to maintain history:

{
  "version": "1.2.0",
  "timestamp": "2026-02-22T10:30:00Z",
  "changes": [
    {
      "type": "update",
      "path": "color.semantic.error",
      "previous": "#DC2626",
      "current": "#EF4444",
      "reason": "Improved contrast ratio"
    }
  ],
  "author": "design-system-sync"
}

Step 4: Multi-Format Export

Export tokens to target formats:

To Swift:

// Generated from design-tokens.json v1.2.0
extension Color {
    enum Semantic {
        static let error = Color(hex: "#EF4444")
    }
}

To CSS:

/* Generated from design-tokens.json v1.2.0 */
:root {
    --color-semantic-error: #EF4444;
}

To Tailwind:

// Generated from design-tokens.json v1.2.0
module.exports = {
    theme: {
        extend: {
            colors: {
                semantic: {
                    error: '#EF4444'
                }
            }
        }
    }
}

Synchronization Workflow

Design File to Code

1. Extract tokens from design file (Figma/Sketch/Penpot)
2. Compare with existing design-tokens.json
3. Detect changes:
   • New tokens (additions)
   • Modified values (updates)
   • Missing tokens (potential deletions)
4. Generate diff report
5. Apply changes with confirmation
6. Export to target formats

Code to Design File

1. Read current design-tokens.json
2. Compare with design file tokens
3. Report drift:
   • Tokens in code but not design
   • Value mismatches
   • Naming inconsistencies
4. Generate suggestions for design updates

Conflict Resolution

When conflicts are detected:

Value Conflicts

## Token Conflict: color.primary

| Source | Value |
|--------|-------|
| Design | #2196F3 |
| Code | #1E88E5 |

Resolution Options:
1. Use design value (update code)
2. Use code value (flag for design update)
3. Keep both (create variant)
4. Manual review

Naming Conflicts

## Naming Conflict

Design: "Primary Blue"
Code: "color.brand.primary"

Suggested mapping:
- Create alias: "Primary Blue" → "color.brand.primary"
- Or rename in design to match code convention

Token Organization

Recommended Structure

{
  "color": {
    "primitive": {
      "blue": { "50": {}, "100": {}, "500": {}, "900": {} }
    },
    "semantic": {
      "background": {},
      "surface": {},
      "text": {},
      "error": {},
      "success": {}
    },
    "component": {
      "button": {
        "primary": {},
        "secondary": {}
      }
    }
  },
  "typography": {
    "fontFamily": {},
    "fontSize": {},
    "fontWeight": {},
    "lineHeight": {}
  },
  "spacing": {},
  "borderRadius": {},
  "shadow": {},
  "duration": {}
}

Token Naming Convention

Level	Pattern	Example
Category	<category>	color
Subcategory	<category>.<subcategory>	color.semantic
Token	<category>.<subcategory>.<name>	color.semantic.error
Variant	<token>.<variant>	color.semantic.error.light

Validation Rules

Before applying changes, validate:

1. Type Consistency:

   • Color values are valid hex/rgb/hsl
   • Dimensions include units
   • Font weights are numeric

2. Reference Integrity:

   • All token references resolve
   • No circular references
   • Aliases point to existing tokens

3. Naming Compliance:

   • Follows established convention
   • No duplicate paths
   • Valid JSON keys

Export Configuration

Configure per-format output:

{
  "exports": {
    "swift": {
      "output": "./Sources/Theme/",
      "template": "swift-extensions",
      "colorFormat": "hex-initializer"
    },
    "css": {
      "output": "./styles/tokens.css",
      "prefix": "--design-",
      "colorFormat": "hex"
    },
    "tailwind": {
      "output": "./tailwind.config.js",
      "mode": "extend",
      "includeCategories": ["color", "spacing", "borderRadius"]
    }
  }
}

Change Report

After sync, generate report:

## Design System Sync Report

**Version**: 1.2.0 → 1.3.0
**Timestamp**: 2026-02-22T10:30:00Z

### Changes Applied

| Category | Added | Updated | Removed |
|----------|-------|---------|---------|
| Colors | 3 | 2 | 0 |
| Typography | 0 | 1 | 0 |
| Spacing | 2 | 0 | 0 |

### Details

#### Added

- `color.semantic.warning`: #F59E0B
- `color.semantic.info`: #3B82F6
- `color.semantic.neutral`: #6B7280

#### Updated

- `color.semantic.error`: #DC2626 → #EF4444 (contrast improvement)
- `typography.fontSize.xl`: 1.25rem → 1.375rem

### Files Updated

- tokens/design-tokens.json
- Sources/Theme/Colors.swift
- styles/tokens.css

Troubleshooting

Sync Fails

Symptoms: Export fails or produces invalid output

Solution:

1. Validate source tokens with JSON schema
2. Check for special characters in token names
3. Verify all references resolve

Version Conflict

Symptoms: Multiple sources have different versions

Solution:

1. Identify authoritative source
2. Generate full diff between versions
3. Merge changes with conflict resolution
4. Increment version after merge

See Also

• design-tokens-extraction skill - Initial token extraction
• /sync-design-system command - Sync tokens to code
• design-token-json style - W3C format output
• design-token-swift style - Swift output format