Design System Management Skill

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

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

Code to Design File

Read current design-tokens.json
Compare with design file tokens
Report drift:
- Tokens in code but not design
- Value mismatches
- Naming inconsistencies
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:

Type Consistency:
- Color values are valid hex/rgb/hsl
- Dimensions include units
- Font weights are numeric
Reference Integrity:
- All token references resolve
- No circular references
- Aliases point to existing tokens
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:

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

Version Conflict

Symptoms: Multiple sources have different versions

Solution:

Identify authoritative source
Generate full diff between versions
Merge changes with conflict resolution
Increment version after merge

Agent Skills: Design System Management

Install this agent skill to your local

Skill Files