Design Tokens Language Server for VS Code
Editor tools for working with DTCG formatted design tokens in CSS, JSON, and YAML files.
[!NOTE]
This is pre-release software. If you encounter bugs or unexpected behavior, please file a detailed issue.
Features
Hover Documentation
Display markdown-formatted token descriptions and values when hovering over token names.
Intelligent Snippets
Auto-complete for design tokens - get code snippets for token values with optional fallbacks.
Diagnostics
DTLS complains when your stylesheet contains a var() call for a design token, but the fallback value doesn't match the token's pre-defined $value.
Code Actions
Toggle the presence of a token var() call's fallback value. Offers to fix wrong token definitions in diagnostics.
Document Color
Display token color values in your source as swatches.
Semantic Tokens
Highlight token references inside token definition files.
Go to Definition
Jump to the position in the tokens file where the token is defined. Can also jump from a token reference in a JSON file to the token's definition.
References
Locate all references to a token in open files, whether in CSS or in the token definition JSON or YAML files.
Quick Start
- Install this extension from the VS Code Marketplace
- Configure token files in your project's
package.json (see Configuration below)
- Start coding - you'll get autocomplete, hover info, and diagnostics for design tokens in CSS, JSON, and YAML files
That's it! The extension includes the Design Tokens Language Server binary, so no additional installation is required.
Configuration
Token Files
Design Tokens Language Server uses the DTCG format for design tokens. If you have a design token file in a different format, you can use style-dictionary to convert it to DTCG.
Add a designTokensLanguageServer block to your project's package.json, with references to token files:
{
"name": "@my-design-system/elements",
"designTokensLanguageServer": {
"prefix": "my-ds",
"tokensFiles": [
"npm:@my-design-system/tokens/tokens.json",
{
"path": "npm:@his-design-system/tokens/tokens.json",
"prefix": "his-ds",
"groupMarkers": ["GROUP"]
},
{
"path": "./docs/docs-site-tokens.json",
"prefix": "docs-site"
},
{
"path": "~/secret-projects/fanciest-tokens.json",
"prefix": "shh"
}
]
}
}
Entries under tokensFiles can be either a string or an object with path and prefix properties. The path property can be a relative path or a deno-style npm specifier.
Extension Settings
This extension contributes the following settings:
designTokensLanguageServer.tokensFiles: List of design token files to watch for changes. Elements can be strings (paths) or objects with path, prefix, and groupMarkers properties.designTokensLanguageServer.prefix: Global prefix for all design tokens. Useful for namespacing your design tokens.designTokensLanguageServer.groupMarkers: List of token names which will be treated as group names (default: ["_", "@", "DEFAULT"]).
Token Prefixes
The DTCG format does not require a prefix for tokens, but it is recommended to use a prefix to avoid conflicts with other design systems. If your token files do not nest all of their tokens under a common prefix, you can pass one yourself in the prefix property.
Group Markers
Because the DTCG format is nested, a conflict can emerge when the token file author wants to define a group of tokens, but have the group name also be a token. For example, --token-color-red and --token-color-red-darker are both valid tokens.
Design Tokens Language Server uses "group markers" to contain the token data for a group. The default group markers are _, @, and DEFAULT.
For example, if you have a token file with the following tokens:
{
"color": {
"red": {
"GROUP": {
"$value": "#FF0000",
"$description": "Red color",
"darker": {
"$value": "#AA0000",
"$description": "Darker red color"
}
}
}
}
}
Then set the groupMarkers property to ["GROUP"] in your package.json:
"designTokensLanguageServer": {
"prefix": "my-ds",
"groupMarkers": ["GROUP"]
}
Supported File Types
- CSS (
.css) - Full design token support with var() functions
- JSON (
.json) - Token definition files
- YAML (
.yaml, .yml) - Token definition files
Troubleshooting
- Verify your project has a
designTokensLanguageServer block in package.json with valid token file paths
- Check the Output panel (View → Output → "Design Tokens Language Server") for error messages
- Ensure token files are valid DTCG format - use a JSON validator to check syntax
- Check file paths - relative paths are resolved from the workspace root
Language Server Won't Start
- Check the Output panel for error messages
- Try restarting VS Code
- Verify the extension is enabled in the Extensions panel
- Report issues on the GitHub repository
Debugging
The server logs to ~/.local/state/design-tokens-language-server/dtls.log by default. You can view these logs for detailed debugging information:
tail -f ~/.local/state/design-tokens-language-server/dtls.log
License
GPL-3.0-only
