Deprecate v5 --color-* tokens (migrate to OKLCH) and remove @graphiql/plugin-explorer (#4416)

## Summary

Collapses the two parallel color systems v6 shipped with — the legacy v5
`--color-*` HSL variables and the v6 OKLCH tokens — down to one, and
removes the last consumer of the old set.

- Migrates every first-party reader of `--color-*` to the v6 OKLCH
tokens in `tokens.css` (core library, `plugin-code-exporter`,
`plugin-collections`, and the `graphiql-webpack` example), following the
idioms already used by the restyled components.
- **Deprecates** `--color-*` rather than deleting it: the v5 README
documented the whole `root.css` variable set as public retheming API,
and the HSL→OKLCH format change rules out a transparent alias. The
variables stay frozen at their v5 values with an inline deprecation
comment; overriding them no longer re-themes GraphiQL, so consumers
should move to the OKLCH tokens.
- **Removes `@graphiql/plugin-explorer`** — the last first-party
`--color-*` reader, now superseded by the default
`@graphiql/plugin-query-builder`. It remains maintained on the v5 LTS
branch.
- Docs: the migration guide gains a `--color-*`→v6 mapping table and its
`plugin-explorer` section moves from deprecation to removal; the READMEs
point retheming at `tokens.css`.

## Test plan

- [ ] On the deploy preview, toggle Light/Dark and confirm text,
borders, icons, hover states, markdown deprecation admonitions, and the
settings dialog all render correctly in both themes.
- [ ] Confirm the default query-builder plugin still opens, and the
explorer plugin is gone from the webpack and CDN examples.
- [ ] In devtools, override `--color-primary` on `.graphiql-container`
and confirm it no longer changes the UI (deprecated); override the
matching OKLCH token (e.g. `--accent-blue`) and confirm it does.

Refs: #4219

Author: trevor-scheer

.changeset/explorer-deprecation.md

@@ -13,7 +13,6 @@
     "graphiql": "5.2.2",
     "@graphiql/plugin-code-exporter": "5.1.1",
     "@graphiql/plugin-doc-explorer": "0.4.1",
-    "@graphiql/plugin-explorer": "5.1.1",
     "@graphiql/plugin-history": "0.4.1",
     "@graphiql/react": "0.37.3",
     "@graphiql/toolkit": "0.11.3",

.changeset/pre.json

@@ -20,11 +20,6 @@ labels: [graphiql, enhancement]
     api:
     https://graphiql-test.netlify.app/typedoc/modules/graphiql_react.html#graphiqlplugin-2
 
-    examples:
-
-    https://github.com/graphql/graphiql/tree/main/packages/graphiql-plugin-explorer
-
-
   In the event that the plugin API doesn't allow you to build a feature, it
   may be that expanding the plugin API *itself* is the best place for the
   feature to be introduced!

.github/ISSUE_TEMPLATE/graphiql-feature.md

@@ -12,7 +12,6 @@ const PACKAGES = [
   'react',
   'react-dom',
   'graphiql',
-  '@graphiql/plugin-explorer',
   '@graphiql/react',
   '@graphiql/toolkit',
   'graphql',
@@ -69,7 +68,6 @@ async function main() {
     'react-dom/': `${cdnUrl('react-dom')}/`,
     graphiql: `${cdnUrl('graphiql')}?standalone&external=react,react-dom,@graphiql/react,graphql`,
     'graphiql/': `${cdnUrl('graphiql')}/`,
-    '@graphiql/plugin-explorer': `${cdnUrl('@graphiql/plugin-explorer')}?standalone&external=react,@graphiql/react,graphql`,
     '@graphiql/react': `${cdnUrl('@graphiql/react')}?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid`,
     '@graphiql/toolkit': `${cdnUrl('@graphiql/toolkit')}?standalone&external=graphql`,
     graphql: cdnUrl('graphql'),
@@ -83,7 +81,6 @@ async function main() {
         cdnUrl('react-dom'),
         cdnUrl('graphiql'),
         `${cdnUrl('graphiql')}?standalone&external=react,react-dom,@graphiql/react,graphql`,
-        cdnUrl('@graphiql/plugin-explorer'),
         `${cdnUrl('@graphiql/react')}?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid`,
         `${cdnUrl('@graphiql/toolkit')}?standalone&external=graphql`,
         cdnUrl('graphql'),
@@ -96,10 +93,6 @@ async function main() {
   // CSS
   const graphiqlCss = `${cdnUrl('graphiql')}/dist/style.css`;
   const graphiqlCssHash = (await fetchIntegrityHash(graphiqlCss))[1];
-  const graphiqlPluginExplorer = `${cdnUrl('@graphiql/plugin-explorer')}/dist/style.css`;
-  const graphiqlPluginExplorerHash = (
-    await fetchIntegrityHash(graphiqlPluginExplorer)
-  )[1];
 
   // Generate index.html
   const templatePath = path.join(
@@ -119,9 +112,7 @@ async function main() {
   const output = template
     .replace('{{IMPORTMAP}}', importMap)
     .replace('{{GRAPHIQL_CSS_URL}}', graphiqlCss)
-    .replace('{{GRAPHIQL_CSS_INTEGRITY}}', graphiqlCssHash)
-    .replace('{{PLUGIN_EXPLORER_CSS_URL}}', graphiqlPluginExplorer)
-    .replace('{{PLUGIN_EXPLORER_CSS_INTEGRITY}}', graphiqlPluginExplorerHash);
+    .replace('{{GRAPHIQL_CSS_INTEGRITY}}', graphiqlCssHash);
 
   console.log(output);
 }

.github/scripts/update-cdn-versions.mjs

@@ -11,7 +11,7 @@ If something in your integration breaks that isn't covered here, please open an
 3. [Removed hooks](#removed-hooks)
 4. [New `transport` prop](#new-transport-prop)
 5. [New first-party plugins](#new-first-party-plugins)
-6. [`@graphiql/plugin-explorer` deprecation](#graphiqlplugin-explorer-deprecation)
+6. [`@graphiql/plugin-explorer` removal](#graphiqlplugin-explorer-removal)
 7. [Theme, density, and font-size settings](#theme-density-and-font-size-settings)
 8. [Considering for removal in v7](#considering-for-removal-in-v7)
 9. [Other notes](#other-notes)
@@ -26,12 +26,12 @@ Most of this is additive and requires no rewrite: the old `fetcher` prop and the
 
 If you don't override GraphiQL's CSS, there's nothing to do here — the new look applies automatically.
 
-If you do retheme GraphiQL by overriding CSS custom properties, the important thing to understand is that v6 does **not** replace the old variables with new ones of the same name — it adds a second, parallel token system alongside them. The v5 variables (`--color-primary`, `--color-neutral`, `--color-base`, and so on, defined under `.graphiql-container` as `h, s%, l%` triplets consumed via `hsl(var(--x))`) are untouched and still there. Components that have been restyled for v6 (buttons, dialogs, tabs, the top bar, the activity rail, the settings dialog, and most of the redesigned chrome) read from a new set of OKLCH tokens in `tokens.css` instead. A handful of pieces — the base text and link rules that apply to every `.graphiql-container`/`.graphiql-dialog`, `ButtonGroup`, `MarkdownContent`, and `@graphiql/plugin-explorer` — still read the v5 variables, unchanged.
+If you do retheme GraphiQL by overriding CSS custom properties, the important thing to understand is that v6 does **not** replace the old variables with new ones of the same name — it adds a second, parallel token system and **deprecates the old one**. The v5 variables (`--color-primary`, `--color-neutral`, `--color-base`, and so on, defined under `.graphiql-container` as `h, s%, l%` triplets consumed via `hsl(var(--x))`) are still defined, frozen at their v5 values, but **no v6 component reads them anymore** — every restyled surface reads a new set of OKLCH tokens in `tokens.css` instead. They're retained only as a frozen compatibility surface for your own custom CSS — no first-party code reads them.
 
 Practically, that means:
 
-- **If you only set a handful of `--color-*` overrides today**, they'll keep applying to whatever still reads them, but they won't touch the restyled surfaces. You'll want to add the new variables to match if you want full coverage.
-- **There is no automatic conversion** between the two systems. Setting `--color-primary` does not change `--accent-blue`, and vice versa. There is no compatibility shim, and the two systems aren't a documented 1:1 mapping — see below and [Considering for removal in v7](#considering-for-removal-in-v7).
+- **Overriding a `--color-*` variable no longer re-themes GraphiQL's built-in UI.** The variables still resolve, so custom CSS of your own that reads them won't break, but because no component reads them, setting `--color-primary` or `--color-neutral` has no effect on the redesigned surfaces. To retheme v6, set the OKLCH tokens instead.
+- **There is no automatic conversion** between the two systems, and no compatibility shim. The formats differ — v5 packs `h, s%, l%` for `hsl()`, v6 packs `L% C H` for `oklch()` — so an old variable can't simply alias a new one. See [Migrating `--color-*` overrides](#migrating---color--overrides) below.
 
 ### The new variable names
 
@@ -50,6 +50,22 @@ There is no published mapping from the nine v5 `--color-*` names to these — th
 
 The v5 variables are still documented in the [`@graphiql/react` README](../../packages/graphiql-react/README.md#theming); the new token file itself, [`tokens.css`](../../packages/graphiql-react/src/style/tokens.css), is the source of truth for the v6 set until the README catches up.
 
+### Migrating `--color-*` overrides
+
+There's no mechanical 1:1 replacement — a single v5 variable often split across several v6 tokens depending on the surface, and which token you want depends on what you're theming. As a starting point, here's where GraphiQL's own internal usages of each v5 variable moved to:
+
+| v5 variable                                             | Role                                    | v6 token(s) GraphiQL now uses                                                                                                                                                            |
+| ------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--color-base`                                          | Surfaces / backgrounds                  | `--bg-canvas` (page), `--bg-elevated` (menus/popovers), `--bg-subtle` (inputs, resting fills), `--bg-overlay` (hover)                                                                    |
+| `--color-neutral`                                       | Body text, icons, borders, subtle fills | Text: `--fg-default` (default), `--fg-muted` (secondary), `--fg-subtle` (icons); borders: `--border-default`, `--border-strong`; translucent fills: `oklch(var(--fg-default) / <alpha>)` |
+| `--color-primary`                                       | Links, primary accent                   | `--accent-blue` (links, accent text/icons); `--btn-primary` + `--btn-primary-border` (filled action buttons)                                                                             |
+| `--color-warning`                                       | Deprecation / warning                   | `--accent-orange` (text/border; `oklch(var(--accent-orange) / 0.1)` for fills)                                                                                                           |
+| `--color-error`                                         | Errors                                  | `--accent-red`                                                                                                                                                                           |
+| `--color-success`                                       | Success                                 | `--accent-green`                                                                                                                                                                         |
+| `--color-secondary`, `--color-tertiary`, `--color-info` | Secondary accents, editor syntax        | The `--accent-*` set in `tokens.css`; editor syntax colors are defined in the Monaco theme, not via CSS variables                                                                        |
+
+Remember these are OKLCH triplets composed with `oklch(var(--x))` (and `oklch(var(--x) / <alpha>)` for transparency), not `hsl()`/`hsla()`.
+
 ### Type-name colors
 
 In the schema-aware plugins — the doc explorer and the query builder — type-name references are colored by their GraphQL kind rather than all sharing one color. This makes a field list easier to scan: leaf types stand out from the objects you drill into.
@@ -425,15 +441,11 @@ import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
 
 Their stylesheets are bundled into `graphiql`'s own `style.css` regardless of whether they're in your `plugins` list, so opting out removes the panel and rail icon but not the (small) amount of CSS from the bundle.
 
-## `@graphiql/plugin-explorer` deprecation
+## `@graphiql/plugin-explorer` removal
 
-`@graphiql/plugin-explorer` — the plugin wrapping OneGraph's `graphiql-explorer` library — is deprecated as of v6. It still works exactly as before: same API, same props, no behavior change. But it wraps a library that is no longer actively maintained upstream, and its role is now filled by the first-party `@graphiql/plugin-query-builder` described above, which is default-installed and covers the same "build a query without typing it" use case with fragment, variable, and union/interface support that `graphiql-explorer` never had.
+`@graphiql/plugin-explorer` — the plugin wrapping OneGraph's `graphiql-explorer` library — is **removed in v6**. It wrapped a library that is no longer actively maintained upstream, and its role is now filled by the first-party `@graphiql/plugin-query-builder` described above, which is default-installed and covers the same "build a query without typing it" use case with fragment, variable, and union/interface support that `graphiql-explorer` never had.
 
-Calling `explorerPlugin()` now logs a one-time console warning:
-
-```
-[@graphiql/plugin-explorer] This package is deprecated. Use the first-party @graphiql/plugin-query-builder instead. Removal planned for v7.
-```
+The package is no longer published from the v6 line. If you still depend on it and can't migrate yet, it remains available on the **v5 LTS branch** — the last `5.x` release stays on npm and is maintained there — but new development targets the query builder.
 
 ### Migrating
 
@@ -465,7 +477,7 @@ If you're using `graphiql` (rather than assembling your own plugin list), the qu
 
 Check the [known limitations](../../packages/graphiql-plugin-query-builder/README.md#known-limitations) in the query builder's README before migrating a heavily-scripted or aliased set of operations — a small number of edge cases (repeated aliased fields, explicit `null` arguments) aren't yet covered.
 
-`@graphiql/plugin-explorer` is not being removed in this release. It continues to receive the same level of maintenance it has for the past several versions (bug fixes as needed; no new features), and removal is planned for a future major version, not this one.
+If you can't migrate before upgrading to v6, pin `@graphiql/plugin-explorer` to its last `5.x` release from npm and track the v5 LTS branch, where it stays maintained.
 
 ## Theme, density, and font-size settings
 
@@ -512,8 +524,7 @@ Nothing below is happening in v6. These are informal signals about where the pro
 
 - **React 18 support.** v6 still supports React 18 and 19 as peer dependencies. A future major version may drop React 18 once the React 19 adoption curve looks similar to where 18 was when 17 support was dropped.
 - **GraphQL.js 15 support.** Similarly, `graphql` `^15.5.0` remains a supported peer range in v6 alongside `^16` and `^17`. Expect the floor to move up in a future major version.
-- **The v5 HSL variable set.** As covered in [CSS and retheming](#css-and-retheming), the old `--color-*` variables are untouched in v6 and still drive any component that hasn't been restyled. Once every component is migrated to the OKLCH token set, keeping the old variables alive means maintaining two parallel theming systems indefinitely for the sake of custom CSS that may or may not still target them. We haven't decided whether that warrants a compatibility shim (translating old variable writes into new tokens) or a straightforward removal once migration is complete. If your integration depends heavily on the v5 variable names, now's a good time to start moving to the new tokens and to weigh in on [discussion #4219](https://github.com/graphql/graphiql/discussions/4219).
-- **`@graphiql/plugin-explorer`.** Covered above — deprecated in v6, planned for removal in v7.
+- **The v5 HSL variable set.** The old `--color-*` variables are **deprecated in v6**. They're still defined — frozen at their v5 values — for backward compatibility, but no v6 component reads them: internal usage was migrated to the OKLCH tokens in `tokens.css` (see [CSS and retheming](#css-and-retheming)). A transparent compatibility shim isn't feasible, because the two systems use different color formats — `h, s%, l%` for `hsl()` versus `L% C H` for `oklch()` — so an old variable can't simply alias a new one. Expect the frozen definitions to be removed in v7. If your integration reads or sets the v5 variable names, migrate to the new tokens now (see [Migrating `--color-*` overrides](#migrating---color--overrides)) and weigh in on [discussion #4219](https://github.com/graphql/graphiql/discussions/4219).
 
 ## Other notes
 

docs/migration/graphiql-6.0.0.md

@@ -1,6 +1,6 @@
 # GraphiQL CDN Example
 
-This is a simple example of using **GraphiQL** directly from a CDN, including the [GraphiQL Explorer plugin](../../packages/graphiql-plugin-explorer/README.md).
+This is a simple example of using **GraphiQL** directly from a CDN.
 
 It loads the latest GraphiQL version from [esm.sh](https://esm.sh), an ESM-based CDN that serves npm packages as ES modules.
 

examples/graphiql-cdn/README.md

@@ -34,12 +34,6 @@
       integrity="sha384-TFpQQKp325U5sd3PddH4cS0KOB3Gz/aqdEe12Mqkkq3wm2MGcDhRX5WhWf+o8akh"
       crossorigin="anonymous"
     />
-    <link
-      rel="stylesheet"
-      href="https://esm.sh/@graphiql/plugin-explorer@5.1.3/dist/style.css"
-      integrity="sha384-vTFGj0krVqwFXLB7kq/VHR0/j2+cCT/B63rge2mULaqnib2OX7DVLUVksTlqvMab"
-      crossorigin="anonymous"
-    />
     <!--
      * Note:
      * The ?standalone flag bundles the module along with all of its `dependencies`, excluding `peerDependencies`, into a single JavaScript file.
@@ -54,7 +48,6 @@
           "react-dom/": "https://esm.sh/react-dom@19.2.7/",
           "graphiql": "https://esm.sh/graphiql@5.2.4?standalone&external=react,react-dom,@graphiql/react,graphql",
           "graphiql/": "https://esm.sh/graphiql@5.2.4/",
-          "@graphiql/plugin-explorer": "https://esm.sh/@graphiql/plugin-explorer@5.1.3?standalone&external=react,@graphiql/react,graphql",
           "@graphiql/react": "https://esm.sh/@graphiql/react@0.37.7?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid",
           "@graphiql/toolkit": "https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql",
           "graphql": "https://esm.sh/graphql@17.0.2",
@@ -65,7 +58,6 @@
           "https://esm.sh/react-dom@19.2.7": "sha384-upKKG1ShVOSXNAoNmdKSl8xWJl9L8fZ05Ki1rHXpPijT4hIS/FFh+88dxk72+jre",
           "https://esm.sh/graphiql@5.2.4": "sha384-3feoWeu5QZYyfhHQyP8i+VBW+tYf58tTwgBb8Fsrw2QlP/YRBR2tscNGcYyRDtHC",
           "https://esm.sh/graphiql@5.2.4?standalone&external=react,react-dom,@graphiql/react,graphql": "sha384-n1sWmquV8wXH/vbn5Q8BaQAw8iAFku5zAs2fPBrht0L/OP4/qgZWL/v/WhMLFPBH",
-          "https://esm.sh/@graphiql/plugin-explorer@5.1.3": "sha384-aDt72jaNBi2he5K4f47qh+xnS6Za54L6vuoNt6KtToLAJfebp23zCaAl3zXGl7dV",
           "https://esm.sh/@graphiql/react@0.37.7?standalone&external=react,react-dom,graphql,@graphiql/toolkit,@emotion/is-prop-valid": "sha384-U8awo9eG6M8scx4fjis/pNfYja4d5EtxOFYcmvDGG8K4Rt/bGB6Km1hxbQXZr9qH",
           "https://esm.sh/@graphiql/toolkit@0.12.1?standalone&external=graphql": "sha384-+cNTwZgIW33q7A4E+ZoCMqzcXdfVIc2VthQvJ0uDpRXERBWYuDKPVMzvdQU8x48o",
           "https://esm.sh/graphql@17.0.2": "sha384-IPvlcmnvWT91sKqwbg9MxPXJUuPmSdwXCp22x6hcbBkAEhlfSKkMLR3v19K9iRUp"
@@ -77,13 +69,12 @@
       import ReactDOM from 'react-dom/client';
       import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
       import { createTransport } from '@graphiql/toolkit';
-      import { explorerPlugin } from '@graphiql/plugin-explorer';
       import 'graphiql/setup-workers/esm.sh';
 
       const transport = createTransport({
         url: 'https://countries.trevorblades.com',
       });
-      const plugins = [HISTORY_PLUGIN, explorerPlugin()];
+      const plugins = [HISTORY_PLUGIN];
 
       function App() {
         return React.createElement(GraphiQL, {

examples/graphiql-cdn/index.html

@@ -10,7 +10,6 @@
   },
   "dependencies": {
     "@graphiql/plugin-code-exporter": "^5.1.2",
-    "@graphiql/plugin-explorer": "^5.1.3",
     "@graphiql/react": "^0.37.7",
     "@graphiql/toolkit": "^0.12.1",
     "graphiql": "^5.2.4",