W3C Color Toolkit

Color highlighting, hover information, an inline swatch with the native color picker, and format conversion for VS Code — all driven by one color engine with CSS Color 3 / 4 / 5 / 6 and CSS Color HDR support.

中文文档: README.zh-cn.md · Changes: CHANGELOG.md

At a glance

All five read the same document color index, so they always agree on the range, the color value, the alpha, the original color space, and whether the value could be resolved at all. Nothing is re-parsed per feature.

Requirements

• VS Code 1.101 or newer.
• No other extension or external tool required.
• Works in remote workspaces and in VS Code for the Web (the extension ships a browser bundle).
• In an untrusted workspace, variables resolve only inside the current document — imported files are not read.

Quick start

1. Install the extension. It activates after startup finishes; no command is needed.
2. Open any file with colors in it — CSS or not.
3. Hover a color: you get a preview swatch, the original syntax, and every enabled format.
4. Click the inline swatch in front of the color to open the native picker and edit the value in place.
5. Put the cursor inside a color and run W3C Color Toolkit: Convert Color (or right-click → W3C Color Toolkit → Convert Color) to rewrite it in another format.
6. Run W3C Color Toolkit: Enable Features to toggle the five features from one Quick Pick, or Configure Color Fields to choose exactly which formats and syntaxes are in scope.

Everything works out of the box. The sections below are the reference for when you want to change it.

Features

Color highlighting

w3cColorToolkit.highlight picks one marker style for the whole extension:

square-before / square-after are the extension's own decoration, so they work in every language and every position and do not depend on VS Code's color feature at all — useful if you turned inline swatches off but still want a visible chip.

Related options: advanced.highlight.markRuler (overview-ruler tick), advanced.highlight.maxMatchesPerDocument, advanced.scan.comments, advanced.scan.strings, advanced.highlight.matchWords (where bare color names count as colors).

Hover information

Hovering a color renders, in this order: the preview swatch, the original source text, then one row per enabled format, then the non-CSS rows (hsv, cmyk), then the meta rows (specification level, parser notes, and — if you enable them — alpha, gamut and the two contrast ratios).

▇▇▇  (preview)
Source: oklch(70% 0.2 30)
Hex: #f0703f
rgb(): rgb(240, 112, 63)
…
Specification: CSS Color 4

Preview appearance: advanced.info.previewSize (small / large) and advanced.info.previewShape (square / rectangle). Meta rows: advanced.info.showSpecLevel, advanced.info.showDiagnostics.

The swatch is rendered as a local SVG data URI built only from sanitised numbers — the raw source text is never interpolated into it.

Inline swatch and the native color picker

The extension registers a DocumentColorProvider, so VS Code draws its inline swatch in front of the color and offers its color picker from that swatch — including oklch(), lab(), color(), color-mix(), relative color syntax, the HDR spaces, and colors inside comments and strings, none of which VS Code's built-in providers cover.

Picking a color rewrites the value in the original format first, falling back to hex, rgb, hsl, oklch, and skipping any format that cannot express the current alpha.

Values that are not a plain color get a read-only swatch — you see the color, but no rewrite is offered, so one stray drag cannot flatten an expression into a literal:

• context dependent values: light-dark(), system colors, currentColor, unresolved var();
• read-only syntax: color-mix(), relative colors, contrast-color(), device-cmyk(), color-layers().

Use Convert Color when you want to rewrite those on purpose.

advanced.colorPicker.mode:

Two VS Code limits apply: at most editor.colorDecoratorsLimit (500 by default) swatches per editor — the extension truncates its report to that number and logs it — and editor.colorDecoratorsActivatedOn decides whether the picker opens on hover, on click, or both.

Format conversion and copying

Convert Color rewrites the value in the document; Copy Color As puts it on the clipboard and leaves the document untouched. Both use the same picker, grouped by category.

How the target color is chosen:

• Empty selection → the color under the cursor.
• Non-empty selection → it must cover exactly one complete color expression; a partial selection is reported as invalid rather than guessed at.
• Multiple selections are supported. All of them are resolved first; the document is written in a single edit only if every selection succeeded, so you never get a half-converted file.

Before writing, conversion tells you whether the value will be gamut mapped, whether alpha will be dropped, and whether none components will be lost. The default policy is to refuse rather than silently lose information — see advanced.convert.alphaLoss, advanced.convert.missingComponentLoss, advanced.convert.namedColorFallback.

Output style: w3cColorToolkit.convertSyntax (legacy commas vs modern spaces for rgb() / hsl()), w3cColorToolkit.precision, advanced.output.hexCase, advanced.output.gamutMapping.

Variable resolution

@import / @use / @forward are followed across files, bounded by advanced.variables.maxImportDepth, advanced.variables.maxImportFiles and cycle detection. Add extra workspace-relative search roots with advanced.variables.includePaths. @color-profile --name { fallback: … } is picked up too, so color(--name …) can resolve.

Context dependent values are never faked

currentColor, the 19 system colors, the 23 deprecated system colors, light-dark(), unresolved var(), a custom @color-profile without a fallback, and non-static alpha all resolve to a contextual state. They are never converted, and unless an explicit preview assumption applies they are not highlighted either: the hover explains what the value depends on instead of showing a made-up swatch. Deprecated system colors also show their replacement keyword.

One case is previewable without guessing: light-dark() picks a branch according to advanced.contextualPreview, whose default auto follows the current editor theme. The hover still labels the result as an assumption, and switching theme re-renders it. Set the option to off for no preview at all.

hdr-color() depends on the display's HDR headroom, so it stays contextual even with the HDR switch on — unless you declare a headroom via advanced.experimental.hdrAssumedHeadroom.

Commands

Five entries appear in the Command Palette (category W3C Color Toolkit):

Convert Color and Copy Color As are also in the editor context menu, under the W3C Color Toolkit submenu.

Manage actions (also registered as individual command ids):

Migrate legacy plug-in settings imports settings you had explicitly set for an older color extension into their w3cColorToolkit equivalents. It shows a preview, writes only after you confirm, never touches the old settings, keeps each scope in that same scope, and is safe to run twice.

Keyboard shortcuts

The 24 direct w3cColorToolkit.convertTo.* commands and the 7 Manage actions are hidden from the Command Palette but fully bindable — they appear in the Keyboard Shortcuts editor. No default keybindings are shipped, to avoid clashing with yours:

// keybindings.json
[
  { "key": "ctrl+alt+h", "command": "w3cColorToolkit.convertTo.hex", "when": "editorTextFocus" },
  { "key": "ctrl+alt+o", "command": "w3cColorToolkit.convertTo.oklch", "when": "editorTextFocus" },
  {
    "key": "ctrl+alt+p",
    "command": "w3cColorToolkit.convertTo.rec2100Pq",
    "when": "editorTextFocus && w3cColorToolkit.hdrEnabled"
  }
]

Command id suffixes follow the format list: hex, rgb, hsl, oklch, hwb, lab, lch, oklab, srgb, srgbLinear, displayP3, displayP3Linear, a98Rgb, prophotoRgb, rec2020, xyzD50, xyzD65, namedColor, ictcp, jzazbz, jzczhz, rec2100Pq, rec2100Hlg, rec2100Linear.

Settings

The 8 settings in the Settings UI

All eight have resource scope, so they can be set per folder.

The advanced object

Everything else is built in with a sensible default and overridden incrementally through w3cColorToolkit.advanced, using flat dotted keys:

{
  "w3cColorToolkit.advanced": {
    "output.hexCase": "upper",
    "highlight.maxMatchesPerDocument": 3000,
    "variables.includePaths": ["src/styles"]
  }
}

In settings.json, typing " inside the object gives you completion, hover docs and range validation for every key. Two snippets are available: All advanced options (with defaults) and Minimal example.

Rules:

• keys you omit keep their built-in default; arrays and objects are replaced as a whole;
• the 8 top-level settings must not appear here — they are ignored with a warning, which removes any ambiguity about precedence;
• unknown keys and wrong types are ignored, out-of-range numbers are clamped, and every case is logged instead of throwing;
• User / Workspace / Folder scopes are merged key by key by the extension, because VS Code replaces object settings wholesale;
• Manage → Show effective configuration prints the merged result with the origin of each key.

All 35 options

Highlight

Color picker

Fields — hover and highlight

Hover

Convert

Output

Scan

Variables

Other

A default this extension overrides

Through contributes.configurationDefaults the extension sets "editor.defaultColorDecorators": "never". Everything VS Code's built-in default provider recognises (hex, rgb(), hsl()) is a subset of what this extension reports, so switching it off removes overlap without losing coverage. The Settings UI shows it as "default value overridden by extension" and you can set it back to auto or always at any time.

Color fields — one list for hover and highlighting

advanced.fields.enabled / advanced.fields.excluded are the single scope for both features, so there is no second place to configure what gets highlighted. Configure Color Fields shows the same grouping, with the applicable scope on every entry.

† requires the cssColorHdr experimental switch. * off by default — add it to fields.enabled or tick it in Configure Color Fields. (Alpha is already visible in the serialised values such as #ff880080; gamut and the contrast ratios are diagnostic detail rather than everyday information.)

Turning a CSS syntax off stops highlighting it; turning a format off also removes its hover row. Syntax the registry does not know about is always highlighted, so a new parser feature never silently loses its decoration.

The order of fields.enabled is the order of the hover rows. Configure Color Fields always writes back in registry order — edit fields.enabled directly if you want a custom order.

Specification support

Run Manage → Show specification support matrix to see the matrix with your current switches applied.

Gamut and HDR handling

• sRGB output uses the CSS-specified gamut mapping by default, not per-channel clipping (advanced.output.gamutMapping can switch to clip or none).
• Wide gamut colors are mapped for the preview swatch only; the hover keeps showing the original value and the gamut status.
• HDR colors are tone mapped for the preview (advanced.highlight.hdrToneMapping) and flagged as tone mapped in the hover.

Troubleshooting

No inline swatch appears. Check editor.colorDecorators (VS Code's own master switch), advanced.colorPicker.mode (must not be off), and whether the file has more than editor.colorDecoratorsLimit (500) colors — the extension truncates at that limit and logs it. The picker is anchored on the swatch, so "picker without swatch" is not possible.

A color shows two swatches. Either colorPicker.mode is all, or another color extension is also reporting that range. dedupe only probes VS Code's built-in CSS provider, in css, less and scss.

Why probing is needed: VS Code renders the results of all color providers without deduplicating by range, it drops the built-in default provider as soon as any extension returns an array (even an empty one), and vscode.executeDocumentColorProvider does not tell you which provider produced which color. Probing the ranges is the only way to guarantee exactly one swatch.

A color is not highlighted. In order of likelihood: w3cColorToolkit.highlight is off; the language is excluded by w3cColorToolkit.languages; the field for that syntax is turned off in Configure Color Fields; the value is context dependent (see above); the document is larger than advanced.scan.maxDocumentSizeKb; there are more colors than advanced.highlight.maxMatchesPerDocument; or it is a bare color name in a non-CSS language and advanced.highlight.matchWords is still css-like.

The picker offers no way to change a value. That is the read-only swatch for context dependent values and read-only syntax. Use Convert Color to rewrite it deliberately.

Conversion was refused. The message names the reason and the line: a contextual value, alpha that the target cannot express (convert.alphaLoss), or no exact color name (convert.namedColorFallback). Loosen the relevant policy, or pick a different target.

var(--x) stays unresolved. Check advanced.variables.resolve, add the stylesheet root to advanced.variables.includePaths, and note that untrusted workspaces do not read imported files. The import walk is bounded by variables.maxImportDepth / maxImportFiles / maxResolveDepth.

A key in advanced seems to be ignored. Run Manage → Show effective configuration — it prints every key with the scope it came from, plus a list of rejected keys. Set advanced.logLevel to debug and open Manage → Open the log for details.

Results look stale. Manage → Rescan the current document, or Clear the index cache. If you hit syntax the extension does not recognise, Manage → Log unsupported syntax records it for a bug report.

Known limitations

• Scanning very large documents is slower than the target performance budget; advanced.scan.maxDocumentSizeKb and advanced.highlight.maxMatchesPerDocument bound the work.
• CSS Color 6 and CSS Color HDR are drafts; values and syntax may still change.
• Untrusted workspaces resolve variables only within the current document.
• No remote ICC profile download; device-cmyk() uses the naive fallback and is marked approximate.

Localisation

English and Simplified Chinese, including the command titles. Other locales fall back to English.

License

MIT — see LICENSE.txt. Third-party notices: NOTICE.md.