Setting up a local design token system

Design tokens are the single source of truth for your brand’s visual properties—colors, typography, spacing, shadows. Rather than hardcoding values across files, a token system lets you update them once and propagate changes everywhere. Local setup beats external services when you need full control and offline access.

Start by choosing a format. JSON works well for most teams, it’s readable and integrates easily with build tools. Create a top-level tokens directory and organize by category: colors, typography, spacing, borders. Within each file, use a naming convention that scales—something like color-primary-500 or spacing-md-16. Keep values semantic, not literal: use names like action-hover rather than blue-brightened.

Next, integrate tokens into your build pipeline. Tools like Style Dictionary or Tokens Studio can transform your JSON into platform-specific outputs—CSS variables, Sass maps, or Swift constants. Most require a single config file that maps inputs to outputs. Run the transformation on every commit to keep generated files in sync. Document the process in your README so teammates know how to add new tokens without breaking the system.

Test your setup end-to-end before committing to it. Create a test component that uses several tokens, then change a token value and verify the change propagates. Check that tokens work in your actual design and development tools—many support live preview. Once comfortable, train your team on the workflow and lock down token creation so changes go through review before deployment.