Design Token Intellisense

Design token intellisense provides IDE autocompletion and hints for design tokens, making tokens discoverable without leaving the editor. Intellisense shows available tokens, their values, and documentation as developers type. This significantly improves developer experience by reducing context switches to documentation.

What Is Design Token Intellisense

Design token intellisense refers to IDE features that provide contextual suggestions, value previews, and documentation for design tokens. This includes CSS custom property completion, JavaScript token object completion, and color/value previews.

Intellisense bridges the gap between token definitions and their usage points.

How Design Token Intellisense Works

CSS custom property intellisense:

/* Typing "var(--color-" triggers suggestions */
.button {
  background: var(--color-primary); /* Autocomplete suggests color tokens */
  color: var(--color-text-on-primary);
  padding: var(--spacing-md);
}

JavaScript token intellisense:

// Typing "tokens." triggers suggestions
import { tokens } from '@company/tokens';

const styles = {
  background: tokens.color.primary, // Autocomplete shows color.* options
  padding: tokens.spacing.md        // Autocomplete shows spacing.* options
};

Value preview:

/* Hovering shows resolved value */
.element {
  background: var(--color-primary); /* Hover: #3B82F6 */
}

VS Code settings for CSS variables:

// .vscode/settings.json
{
  "css.customData": [".vscode/tokens.css-data.json"],
  "editor.quickSuggestions": {
    "strings": true
  }
}

Custom CSS data file:

// .vscode/tokens.css-data.json
{
  "version": 1.1,
  "properties": [
    {
      "name": "--color-primary",
      "description": "Primary brand color",
      "syntax": "<color>",
      "values": [{ "name": "#3B82F6" }]
    },
    {
      "name": "--spacing-md",
      "description": "Medium spacing (16px)",
      "syntax": "<length>",
      "values": [{ "name": "16px" }]
    }
  ]
}

Key Considerations

• Intellisense data should be generated from token sources
• IDE-specific configurations may be needed
• Documentation in intellisense aids understanding
• Value previews provide visual feedback
• Regeneration should accompany token updates
• Team should use consistent IDE configurations
• Extensions can enhance base capabilities
• Performance may degrade with very large token sets

Common Questions

How should VS Code be configured?

VS Code configuration enables CSS and JavaScript intellisense.

CSS custom properties:

// Generate CSS data from tokens
function generateCSSData(tokens) {
  return {
    version: 1.1,
    properties: tokens.map(token => ({
      name: `--${token.cssName}`,
      description: token.description || `Value: ${token.value}`,
      syntax: getSyntax(token.type)
    }))
  };
}

// Write to .vscode/tokens.css-data.json

Settings configuration:

// .vscode/settings.json
{
  "css.customData": [".vscode/tokens.css-data.json"],
  "scss.customData": [".vscode/tokens.css-data.json"],
  "editor.quickSuggestions": {
    "strings": true,
    "comments": false,
    "other": true
  }
}

Extensions recommendation:

// .vscode/extensions.json
{
  "recommendations": [
    "bradlc.vscode-tailwindcss",
    "csstools.postcss",
    "stylelint.vscode-stylelint"
  ]
}

How should JavaScript/TypeScript intellisense work?

JavaScript intellisense relies on TypeScript definitions.

Type definitions for autocomplete:

// Detailed interface for better autocomplete
export interface ColorTokens {
  /** Primary brand color (#3B82F6) */
  primary: string;
  /** Secondary brand color */
  secondary: string;
  /** Text colors */
  text: {
    /** Primary text color for body content */
    primary: string;
    /** Secondary text color for less emphasis */
    secondary: string;
  };
}

JSDoc comments enhance hints:

/**
 * Design system spacing tokens
 * @example
 * padding: tokens.spacing.md // 16px
 */
export interface SpacingTokens {
  /** Extra small spacing (4px) */
  xs: number;
  /** Small spacing (8px) */
  sm: number;
  /** Medium spacing (16px) - default for component padding */
  md: number;
  /** Large spacing (24px) */
  lg: number;
}

Package.json types field:

{
  "types": "./dist/tokens.d.ts",
  "typesVersions": {
    "*": {
      "*": ["dist/tokens.d.ts"]
    }
  }
}

How should intellisense be generated automatically?

Automation keeps intellisense data synchronized.

Build script integration:

// generate-intellisense.js
const tokens = require('./dist/tokens.json');

// Generate VS Code CSS data
const cssData = {
  version: 1.1,
  properties: tokens.map(t => ({
    name: `--${t.name.replace(/\./g, '-')}`,
    description: `${t.description || ''}\nValue: ${t.value}`,
    syntax: getSyntaxForType(t.type)
  }))
};

fs.writeFileSync('.vscode/tokens.css-data.json', JSON.stringify(cssData, null, 2));

Package script:

{
  "scripts": {
    "build": "npm run build:tokens && npm run build:intellisense",
    "build:intellisense": "node scripts/generate-intellisense.js"
  }
}

Git tracking:

# Track intellisense data for team consistency
# .vscode/tokens.css-data.json - tracked

Summary

Design token intellisense provides IDE autocompletion that makes tokens discoverable during development. VS Code configuration through custom CSS data files enables CSS custom property hints. TypeScript definitions with JSDoc comments enable JavaScript intellisense with documentation. Automated generation from token sources keeps intellisense synchronized. Proper team configuration ensures consistent developer experience across the team.