How to Edit Design Tokens

This guide walks through the complete workflow for editing design tokens, from source files to verification in Storybook.

📋 Prerequisites

Basic understanding of JSON
Access to the CloudAlt monorepo
Node.js and Yarn installed
Storybook running (optional but recommended)

🎯 Understanding the System

Token Flow

1. Edit Source Token (JSON)
         ↓
2. Run `yarn build` (Style Dictionary)
         ↓
3. Generate Output Files (CSS, JS, JSON, etc.)
         ↓
4. Storybook/Apps Import & Display

Key Principle: Always edit source tokens in tokens/ directory, never edit build outputs.

📝 Common Scenarios

Scenario 1: Change an App’s Primary Color

Goal: Change HostGuest web from slate grey to navy blue

Steps:

Navigate to the token file

cd packages/design-tokens
open tokens/apps/stay-overnight/hostguest-web.json

Edit the primary color value

{
  "app": {
    "hostguest-web": {
      "colors": {
        "primary": {
          "value": "#191970",  // ← Changed from #334155 to navy
          "type": "color",
          "description": "Navy Blue - Primary brand color"
        }
      }
    }
  }
}

Rebuild the tokens
Terminal window
```
yarn build
```
Verify in Storybook
- Navigate to http://localhost:6006/
- Go to “Brand Tokens” → “Stay Overnight Division”
- Confirm HostGuest shows navy blue

Result: ✅ HostGuest now uses navy blue. All other apps unchanged.

Scenario 2: Add a New App

Goal: Add a new app called “GreenGuest Web” to Stay Overnight

Steps:

Create new app token file

cd packages/design-tokens/tokens/apps/stay-overnight
touch greenguest-web.json

Define app colors

{
  "app": {
    "greenguest-web": {
      "name": { "value": "GreenGuest Web", "type": "string" },
      "description": {
        "value": "Eco-friendly Stay Overnight experience - web platform",
        "type": "string"
      },
      "colors": {
        "primary": {
          "value": "#228B22",
          "type": "color",
          "description": "Forest Green - Primary brand color"
        },
        "secondary": {
          "value": "#90EE90",
          "type": "color",
          "description": "Light green for secondary elements"
        },
        "accent": {
          "value": "#006400",
          "type": "color",
          "description": "Dark green accent"
        }
      }
    }
  }
}

Rebuild tokens
Terminal window
```
cd packages/design-tokens
yarn build
```

Update Storybook story (if you want it displayed)

// In packages/storybook/stories/DesignSystem/BrandTokens.stories.tsx
// Add to StayOvernightDivision story:
const greenguest = [
  {
    name: 'GreenGuest',
    color: tokens.app['greenguest-web'].colors.primary,
    description: 'Forest Green - Eco-friendly brand'
  }
];

Verify
- Rebuild Storybook if needed
- Check that GreenGuest appears in the story

Result: ✅ New app token created and available system-wide.

Scenario 3: Change Division-Wide Spacing

Goal: Make Stay Match spacing more compact (reduce by 25%)

Steps:

Open division spacing file

open packages/design-tokens/tokens/divisions/stay-match/spacing.json

Edit spacing values

{
  "spacing": {
    "0": { "value": "0", "type": "spacing" },
    "1": { "value": "0.1875rem", "type": "spacing", "description": "3px (was 4px)" },
    "2": { "value": "0.375rem", "type": "spacing", "description": "6px (was 8px)" },
    "3": { "value": "0.5625rem", "type": "spacing", "description": "9px (was 12px)" },
    "4": { "value": "0.75rem", "type": "spacing", "description": "12px (was 16px)" },
    // ... continue pattern for all values
  }
}

Rebuild tokens
Terminal window
```
cd packages/design-tokens
yarn build
```
Test in apps
- All Stay Match apps now use tighter spacing
- Other divisions unchanged

Result: ✅ All Stay Match apps have 25% less spacing between elements.

Scenario 4: Override Semantic Color for One App

Goal: Make “success” green brighter for pinkGuest (better contrast with pink)

Steps:

Open app token file

open packages/design-tokens/tokens/apps/stay-overnight/pinkguest-web.json

Add semantic override

{
  "app": {
    "pinkguest-web": {
      "colors": {
        "primary": { "value": "#F90772", "type": "color" },
        "secondary": { "value": "#FFC0CB", "type": "color" },
        "accent": { "value": "#FF1493", "type": "color" }
      },
      "semantic": {
        "success": {
          "value": "#00FF7F",
          "type": "color",
          "description": "Spring Green - brighter success for pink theme"
        }
      }
    }
  }
}

Rebuild
Terminal window
```
cd packages/design-tokens
yarn build
```
Verify
- pinkGuest uses #00FF7F for success messages
- All other apps still use global #10B981

Result: ✅ pinkGuest has custom success color, others unchanged.

Scenario 5: Change Typography for a Division

Goal: Use a different font for Pride City division

Steps:

Open division typography file

open packages/design-tokens/tokens/divisions/pride-city/typography.json

Change font family

{
  "font": {
    "family": {
      "primary": {
        "value": "'Poppins', system-ui, -apple-system, sans-serif",
        "type": "fontFamily",
        "description": "Poppins - Modern font for Pride City"
      },
      "heading": {
        "value": "'Poppins', system-ui, -apple-system, sans-serif",
        "type": "fontFamily",
        "description": "Poppins for headings"
      }
    },
    // ... keep size, weight, lineHeight, letterSpacing unchanged
  }
}

Load the font (in app or Storybook)

<!-- Add to <head> -->
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700;900&display=swap" rel="stylesheet">

Rebuild tokens
Terminal window
```
cd packages/design-tokens
yarn build
```
Verify
- Pride City apps now use Poppins
- Other divisions still use Inclusive Sans

Result: ✅ Pride City division has unique typography.

🔧 Troubleshooting

Problem: Changes don’t appear in Storybook

Solution:

Verify you ran yarn build in packages/design-tokens
Check Storybook is importing from build/json/tokens.json
Hard refresh browser (Cmd+Shift+R)
Restart Storybook if needed

Problem: Token collision warnings

Cause: Multiple files defining the same token (usually font weights across divisions)

Solution: These are safe if values match. To eliminate:

Move shared tokens to global level
Or use log.warnings.disabled: ["TOKEN_COLLISION_WARN"] in config

Problem: Build fails with “Cannot read property”

Cause: Invalid JSON syntax

Solution:

Check JSON is valid (no trailing commas, proper quotes)
Validate with jsonlint or VS Code
Check file follows token schema (value, type, description)

✅ Best Practices Checklist

Before committing token changes:

Ran yarn build and checked for errors
Verified changes in Storybook
Checked color contrast (WCAG AA: 4.5:1 for text)
Added meaningful description fields
Tested on both light and dark modes (if applicable)
Updated documentation if adding new categories
Committed only source files (not build outputs)

📚 Token File Structure Reference

Minimal App Token

{
  "app": {
    "myapp-web": {
      "name": { "value": "My App", "type": "string" },
      "description": { "value": "App description", "type": "string" },
      "colors": {
        "primary": { "value": "#FF0000", "type": "color" }
      }
    }
  }
}

Full App Token with Overrides

{
  "app": {
    "myapp-web": {
      "name": { "value": "My App", "type": "string" },
      "description": { "value": "App description", "type": "string" },
      "colors": {
        "primary": { "value": "#FF0000", "type": "color", "description": "Red primary" },
        "secondary": { "value": "#00FF00", "type": "color", "description": "Green secondary" },
        "accent": { "value": "#0000FF", "type": "color", "description": "Blue accent" }
      },
      "semantic": {
        "success": { "value": "#00D084", "type": "color", "description": "Custom success" },
        "error": { "value": "#FF0000", "type": "color", "description": "Custom error" }
      }
    }
  }
}

🚀 Quick Commands

# Edit app colors
vim tokens/apps/{division}/{app}.json

# Edit division spacing
vim tokens/divisions/{division}/spacing.json

# Edit global semantics
vim tokens/global/semantic-colors.json

# Rebuild (always required after edits)
cd packages/design-tokens && yarn build

# Start Storybook (if not running)
yarn nx storybook storybook

# Verify build output
cat build/json/tokens.json | jq '.app["hostguest-web"]'

💡 Pro Tips

Use VS Code with JSON schema - Enables autocomplete for token properties
Keep a color palette reference - Document hex codes with names
Test on real devices - Colors look different on mobile screens
Use browser DevTools - Inspect CSS variables in web apps
Version control - Commit token changes separately from app code

Design Token System Overview - Architecture and concepts
Storybook Token Browser - Visual token reference
Style Dictionary Docs - Token transformation framework

Need help? Check the Storybook examples for real token usage patterns.

How to Edit Design Tokens

How to Edit Design Tokens

📋 Prerequisites

🎯 Understanding the System

Token Flow

📝 Common Scenarios

Scenario 1: Change an App’s Primary Color

Scenario 2: Add a New App

Scenario 3: Change Division-Wide Spacing

Scenario 4: Override Semantic Color for One App

Scenario 5: Change Typography for a Division

🔧 Troubleshooting

Problem: Changes don’t appear in Storybook

Problem: Token collision warnings

Problem: Build fails with “Cannot read property”

✅ Best Practices Checklist

📚 Token File Structure Reference

Minimal App Token

Full App Token with Overrides

🚀 Quick Commands

💡 Pro Tips

🔗 Related Documentation