Design tokens setup for DesignOps teams using TypeScript

Define tokens, align design + code, and ship a scalable theming foundation. Tailored for DesignOps teams shipping with TypeScript.

Use this playbook to scope work, align design and engineering, and avoid the failure modes we see most often on TypeScript teams.

Who this is for: DesignOps teams shipping design tokens setup on TypeScript.

Typical constraints: serve many designers, tooling budget scrutiny, must prove ROI.

Success looks like: Reduced review cycle time and fewer design-to-dev regressions.

TypeScript focus areas: Export discriminated unions for variant props instead of loose strings.; Generate docs from types where possible (Storybook docgen, TSDoc)..

Watch for: Over-wide props types that accept any string and hide invalid combinations

• Figma variables and CSS custom properties use different names
• Dark mode is bolted on instead of designed as a theme
• Brand updates require manual find-and-replace across repos
• Spacing and typography drift because primitives are undefined
• Over-wide props types that accept any string and hide invalid combinations
• Breaking changes shipped without codemods or deprecation warnings
• Duplicate type definitions between design tokens and component props

1. Audit existing color, type, and spacing decisions in design and code.
2. Define semantic tokens that survive brand refreshes.
3. Wire Figma variables to code exports your CI can validate.
4. Roll out themes incrementally with a deprecation plan for legacy values.

TypeScript specifics:

• Export discriminated unions for variant props instead of loose strings.
• Generate docs from types where possible (Storybook docgen, TSDoc).
• Strict mode for the library package even if app code is gradual.

• Token taxonomy (primitive → semantic → component)
• Figma variables and code export pipeline
• Theme switching strategy (light/dark/high-contrast)
• Migration guide for existing hardcoded values