🎨 Design Tokens Language Server 🪙
Editor tools for working with DTCG formatted design tokens in CSS, and
for token definitions in JSON or YAML files.
[!NOTE]
This pre-release software. If you encounter bugs or unexpected behavior,
please file a detailed issue.
✨ Features
⛸️ Hover Docs
Display markdown-formatted token descriptions and value when hovering over token
names.
✂️ 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, e.g. 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.
Go to definition in a split window using Neovim's
<C-w C-]> binding,
which defers to LSP methods when they're available
🗺️ References
Locate all references to a token in open files, whether in CSS or in the token
definition JSON or YAML files
🧰 Usage
Download the latest release for your platform and place the binary in your
$PATH, renaming it to design-tokens-language-server.
🛻 Installation
Neovim
---@type vim.lsp.ClientConfig
return {
cmd = { 'design-tokens-language-server' },
root_markers = { 'package.json', '.git' },
filetypes = { 'css', 'json' },
}
VSCode
Install from the
vscode marketplace.
Other editors
You can also build development extension for Zed. See
deno.json for more info.
⚙️ Configuration
In order to use DTLS, you need to first configure it to know where to find your
design tokens, and you can also provide it with options for how to deal with
them.
🪙 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.
You can configure the language server globally on on a per-project basis.
Per-project configuration is done via a designTokensLanguageServer block in
your project's package.json.
[!NOTE]
If you have better ideas on how to source token files in a given project,
Please open an issue with your suggestions.
Add a designTokensLanguageServer block to your project's package.json, with
references to tokens files. 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.
{
"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"
}
]
}
}
Global configuration
You can set up global configuration in your editor's LSP settings for DTLS. This
configuration will be used as fallbacks for all projects. There's no need to set
them if your project already has a designTokensLanguageServer block in its
package.json.
For example, in your lsp config for neovim:
return {
cmd = { 'design-tokens-language-server' },
root_markers = { 'package.json', '.git' },
filetypes = { 'css' },
settings = {
dtls = {
tokensFiles = {
{
path = "~/path/to/tokens.json",
prefix = "my-ds",
},
}
}
}
}
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 of the token file object.
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, but unless the author manually prefixes each token in the red
group with red-, it would not be possible to define a token called
--token-color-red.
Design Tokens Language Server therefore has a concept of "group markers" to
contain the token data for a group. The group marker is a well-known token name
that is used to represent the group's top-most token.
The default group markers are _, @, and DEFAULT, because those are
examples mentioned in the various issues on DTCG and style-dictionary which
address the problem of tokens which are also groups.
If you include the groupMarkers property (either project-wide or for a
specific token file), then tokens with the same name as any of the group markers
will be treated as a group, and that tokens's data will be used for the group
name, minus the group marker.
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 for
that particular token file, or globally for all token files in your editor
settings.
"designTokensLanguageServer": {
"prefix": "my-ds",
"groupMarkers": ["GROUP"],
},
🤝 Contributing
🏗️ Building
[!WARNING]
DTLS is developed on Linux, works on macOS, but might not work on Windows. If
you need Windows support, please open an issue.
Install Deno and clone this repo. Run this task to build
and install the binary to ~/.local/bin/design-tokens-language-server:
deno task install
🧪 Testing
Run tests with:
deno task test
Watch tests with:
deno task test:watch
Generate coverage reports with:
deno task coverage
🪲 Debugging
The server logs to ~/.local/state/design-tokens-language-server/dtls.log by
default.
tail -f ~/.local/state/design-tokens-language-server/dtls.log
If you'd like to trace lsp messages in real time, try
lsp-devtools
