From 58de6268e50651ca46160261fbe2854372b18d2c Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 7 May 2026 10:57:00 -0700
Subject: [PATCH 01/38] Enable alpha releases on `graphiql-6` (#4227)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- Swap the vestigial `graphiql-5` reference in
`.github/workflows/release.yml` for `graphiql-6` so the
changesets-action runs on pushes to the integration branch.
- Enter changesets pre-mode with the `alpha` tag so merges aggregate
into `6.0.0-alpha.N` prereleases.
- Add a changeset that seeds the alpha release line by bumping
`graphiql` to v6. No functional change — subsequent alphas accumulate
the redesign work.

## Test plan

- [ ] On merge: changesets-action opens a "Version Packages (alpha)" PR
bumping `graphiql` to `6.0.0-alpha.0`.
- [ ] Merging the version PR publishes `graphiql@6.0.0-alpha.0` to npm
with the `alpha` dist-tag.

Refs: graphql/graphiql#4219
---
 .changeset/pre.json           | 29 +++++++++++++++++++++++++++++
 .changeset/v6-alpha-line.md   |  5 +++++
 .github/workflows/release.yml |  2 +-
 3 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/pre.json
 create mode 100644 .changeset/v6-alpha-line.md

diff --git a/.changeset/pre.json b/.changeset/pre.json
new file mode 100644
index 00000000000..b27ac73cadd
--- /dev/null
+++ b/.changeset/pre.json
@@ -0,0 +1,29 @@
+{
+  "mode": "pre",
+  "tag": "alpha",
+  "initialVersions": {
+    "example-graphiql-vite": "0.0.0",
+    "example-graphiql-vite-react-router": "1.0.0",
+    "example-graphiql-webpack": "0.0.0",
+    "example-monaco-graphql-nextjs": "0.0.0",
+    "example-monaco-graphql-react-vite": "0.0.0",
+    "example-monaco-graphql-webpack": "0.0.0",
+    "cm6-graphql": "0.2.1",
+    "codemirror-graphql": "2.2.4",
+    "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",
+    "graphql-language-service": "5.5.0",
+    "graphql-language-service-cli": "3.5.0",
+    "graphql-language-service-server": "2.14.8",
+    "monaco-graphql": "1.7.3",
+    "vscode-graphql": "0.13.2",
+    "vscode-graphql-execution": "0.3.2",
+    "vscode-graphql-syntax": "1.3.8"
+  },
+  "changesets": []
+}
diff --git a/.changeset/v6-alpha-line.md b/.changeset/v6-alpha-line.md
new file mode 100644
index 00000000000..751f5642634
--- /dev/null
+++ b/.changeset/v6-alpha-line.md
@@ -0,0 +1,5 @@
+---
+'graphiql': major
+---
+
+Initial v6 alpha. Refs graphql/graphiql#4219.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8dfb4fde68a..c8f787eccc3 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -2,7 +2,7 @@ name: Release
 
 on:
   push:
-    branches: [main, graphiql-5]
+    branches: [main, graphiql-6]
 permissions: {}
 jobs:
   release:

From e21fc3f0222cc0f4c3051901cd28c493431ec641 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 7 May 2026 23:20:19 -0700
Subject: [PATCH 02/38] fix formatting after merge conflict resolution

---
 .github/workflows/release.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 260a60d3fb6..a54c3b05b63 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -39,7 +39,7 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version-file: ".node-version"
+          node-version-file: '.node-version'
           cache: yarn
 
       - run: yarn install --frozen-lockfile --immutable

From 8eebea769289e8ac9779c8932926a9afb1950b78 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 8 May 2026 23:11:02 +0000
Subject: [PATCH 03/38] trigger ci


From 72e897082bbec4b67a26bf958c6205fefb64aa77 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 8 May 2026 19:36:00 -0700
Subject: [PATCH 04/38] v6: Add OKLCH design tokens (dark + light) (#4242)

## Summary

- Introduce a new `packages/graphiql-react/src/style/tokens.css` with
the v6 OKLCH-based design token system. Both dark and light palettes
ship together.
- Light theme activates explicitly via `data-theme="light"` or
automatically via `prefers-color-scheme: light` when no theme is pinned.
Dark remains the default.
- Existing v5 HSL variables are unchanged; nothing in `@graphiql/react`
references the new tokens yet.
- Future PRs will restyle components to consume the new tokens and shim
the v5 variables.

Refs: graphql/graphiql#4219
---
 .changeset/oklch-tokens.md                   |   5 +
 packages/graphiql-react/src/style/root.css   |   1 +
 packages/graphiql-react/src/style/tokens.css | 152 +++++++++++++++++++
 resources/custom-words.txt                   |   2 +
 4 files changed, 160 insertions(+)
 create mode 100644 .changeset/oklch-tokens.md
 create mode 100644 packages/graphiql-react/src/style/tokens.css

diff --git a/.changeset/oklch-tokens.md b/.changeset/oklch-tokens.md
new file mode 100644
index 00000000000..6e268cf5ada
--- /dev/null
+++ b/.changeset/oklch-tokens.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Introduce the v6 OKLCH design-token system with both dark and light theme palettes. Tokens (`--bg-canvas`, `--fg-default`, `--accent-blue`, etc.) are stored as OKLCH triplets so opacity can be combined at the call site. Themes are keyed off `data-theme` (`dark` is the default; `light` activates explicitly or via `prefers-color-scheme: light` when no override is set). Existing v5 variables are unchanged; component styles continue to use them until they are migrated.
diff --git a/packages/graphiql-react/src/style/root.css b/packages/graphiql-react/src/style/root.css
index 4bce741a1dd..d8d63da1462 100644
--- a/packages/graphiql-react/src/style/root.css
+++ b/packages/graphiql-react/src/style/root.css
@@ -1,3 +1,4 @@
+@import 'tokens.css';
 @import 'auto-insertion.css';
 @import 'editor.css';
 
diff --git a/packages/graphiql-react/src/style/tokens.css b/packages/graphiql-react/src/style/tokens.css
new file mode 100644
index 00000000000..1b1a1674062
--- /dev/null
+++ b/packages/graphiql-react/src/style/tokens.css
@@ -0,0 +1,152 @@
+/*
+ * v6 design tokens.
+ *
+ * Color tokens are stored as OKLCH component triplets (L% C H) so callers
+ * can combine them with alpha at the use site:
+ *
+ *     background: oklch(var(--bg-canvas));
+ *     color: oklch(var(--fg-default) / 0.6);
+ *
+ * Variable names defined here are the supported retheming surface; class
+ * names and internal selectors are not public API.
+ */
+
+:root,
+[data-theme='dark'] {
+  /* Backgrounds */
+  --bg-canvas: 17.63% 0.014 258; /* #0D1117 */
+  --bg-elevated: 10.39% 0.019 248; /* #010409 */
+  --bg-subtle: 22.02% 0.016 257; /* #161B22 */
+  --bg-overlay: 26.66% 0.015 257; /* #21262D */
+
+  /* Borders */
+  --border-default: 24.58% 0.015 257; /* #1C2128 */
+  --border-muted: 26.66% 0.015 257; /* #21262D */
+  --border-strong: 33% 0.015 252; /* #30363D */
+
+  /* Foreground */
+  --fg-default: 85.69% 0.014 248; /* #C9D1D9 */
+  --fg-strong: 97.03% 0.01 248; /* #F0F6FC */
+  --fg-muted: 66.25% 0.018 251; /* #8B949E */
+  --fg-subtle: 61.37% 0.019 256; /* #7D8590 */
+  --fg-disabled: 56.29% 0.02 256; /* #6E7681 */
+  --fg-dim: 42.47% 0.017 255; /* #484F58 */
+
+  /* Accents */
+  --accent-blue: 78.57% 0.115 247; /* #79C0FF */
+  --accent-green: 69.51% 0.181 146; /* #3FB950 */
+  --accent-green-light: 84.16% 0.164 146; /* #7EE787 */
+  --accent-yellow: 85.74% 0.133 90; /* #F2CC60 */
+  --accent-orange: 79.91% 0.141 60; /* #FFA657 */
+  --accent-red: 66.51% 0.205 27; /* #F85149 */
+  --accent-purple: 80.05% 0.127 306; /* #D2A8FF */
+  --accent-pink: 73.45% 0.163 26; /* #FF7B72 */
+
+  /* Action button (Run) */
+  --btn-primary: 54.6% 0.147 146; /* #238636 */
+  --btn-primary-border: 62.22% 0.166 146; /* #2EA043 */
+
+  /* Typography */
+  --font-family: 'Inter', ui-sans-serif, system-ui, sans-serif;
+  --font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
+  --font-size-body: 13px;
+  --font-size-small: 11px;
+  --font-size-mono: 12px;
+  --font-size-eyebrow: 10.5px;
+  --line-height-body: 18px;
+  --letter-spacing-ui: -0.005em;
+
+  /* Spacing scale */
+  --px-4: 4px;
+  --px-6: 6px;
+  --px-8: 8px;
+  --px-10: 10px;
+  --px-12: 12px;
+  --px-14: 14px;
+  --px-16: 16px;
+  --px-24: 24px;
+  --px-32: 32px;
+
+  /* Layout dimensions */
+  --top-bar-height: 40px;
+  --status-bar-height: 24px;
+  --rail-width: 48px;
+  --side-panel-width: 340px;
+  --tab-strip-height: 32px;
+
+  /* Radii */
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --radius-lg: 8px;
+}
+
+[data-theme='light'] {
+  /* Backgrounds */
+  --bg-canvas: 99% 0.005 248;
+  --bg-elevated: 100% 0 248;
+  --bg-subtle: 96% 0.008 248;
+  --bg-overlay: 92% 0.01 248;
+
+  /* Borders */
+  --border-default: 90% 0.01 248;
+  --border-muted: 85% 0.01 248;
+  --border-strong: 78% 0.012 248;
+
+  /* Foreground */
+  --fg-default: 20% 0.013 248;
+  --fg-strong: 12% 0.011 248;
+  --fg-muted: 40% 0.013 248;
+  --fg-subtle: 50% 0.012 248;
+  --fg-disabled: 65% 0.012 248;
+  --fg-dim: 75% 0.011 248;
+
+  /* Accents — slightly darker / more saturated for AA contrast on light bg */
+  --accent-blue: 50% 0.193 248;
+  --accent-green: 50% 0.176 145;
+  --accent-green-light: 65% 0.19 145;
+  --accent-yellow: 70% 0.15 86;
+  --accent-orange: 62% 0.165 60;
+  --accent-red: 55% 0.224 27;
+  --accent-purple: 55% 0.18 295;
+  --accent-pink: 58% 0.22 17;
+
+  /* Action button (Run) — keeps the green; inverted bg lets it stand out */
+  --btn-primary: 51% 0.15 145;
+  --btn-primary-border: 45% 0.17 145;
+
+  /* Typography, spacing, dimensions, and radii are inherited from :root. */
+}
+
+/*
+ * Apply light overrides automatically when the system prefers light and the
+ * user has not pinned dark. The values are duplicated rather than relying on
+ * inheritance into a media query, which can resolve inconsistently across
+ * browsers when the source rule is keyed off a different selector.
+ */
+@media (prefers-color-scheme: light) {
+  :root:not([data-theme='dark']) {
+    --bg-canvas: 99% 0.005 248;
+    --bg-elevated: 100% 0 248;
+    --bg-subtle: 96% 0.008 248;
+    --bg-overlay: 92% 0.01 248;
+    --border-default: 90% 0.01 248;
+    --border-muted: 85% 0.01 248;
+    --border-strong: 78% 0.012 248;
+    --fg-default: 20% 0.013 248;
+    --fg-strong: 12% 0.011 248;
+    --fg-muted: 40% 0.013 248;
+    --fg-subtle: 50% 0.012 248;
+    --fg-disabled: 65% 0.012 248;
+    --fg-dim: 75% 0.011 248;
+    --accent-blue: 50% 0.193 248;
+    --accent-green: 50% 0.176 145;
+    --accent-green-light: 65% 0.19 145;
+    --accent-yellow: 70% 0.15 86;
+    --accent-orange: 62% 0.165 60;
+    --accent-red: 55% 0.224 27;
+    --accent-purple: 55% 0.18 295;
+    --accent-pink: 58% 0.22 17;
+    --btn-primary: 51% 0.15 145;
+    --btn-primary-border: 45% 0.17 145;
+  }
+}
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index ab691a503e4..e2737fd1f2b 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -153,6 +153,7 @@ nullthrows
 nulltype
 nvim
 objectvalues
+oklch
 onig
 ooops
 orche
@@ -182,6 +183,7 @@ randomthing
 ravikoti
 resi
 resizer
+retheming
 rikki
 roadmap
 roboto

From d9873c3abd0717bc5901010e945c886d9017e002 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Wed, 13 May 2026 05:25:58 -0700
Subject: [PATCH 05/38] v6: Set up Storybook in `@graphiql/react` (#4254)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Storybook gives us a fast feedback loop for iterating on the look of the
app and individual components — flipping themes/density/font-size
without spinning up the full GraphiQL shell.

- Bootstrap Storybook 10 in `@graphiql/react`. Stories colocated as
`<component>.stories.tsx`; ships one starter (`Spinner`) to validate the
pipeline.
- A global decorator wraps every story in `.graphiql-container` with
`data-theme` / `data-density` / `data-font-size` attributes, toggleable
from the Storybook toolbar.
- Move `Uri`, `KeyMod`, `KeyCode`, and `Range` out of the `utility`
barrel into direct imports from `utility/monaco-ssr`. The barrel was
bundling two unrelated concerns — lightweight UI helpers (`cn`, `pick`,
etc.) and heavy Monaco re-exports — so any story reaching for `cn`
transitively pulled Monaco's ESM bundle, which doesn't initialize
cleanly inside Storybook's preview iframe. Splitting them keeps UI
primitives lightweight.

## Run locally

From the repo root:

```
yarn storybook         # dev server on http://localhost:6006
yarn build-storybook   # static build under packages/graphiql-react/storybook-static
```

Refs: graphql/graphiql#4219
---
 .gitignore                                    |   2 +
 package.json                                  |   2 +
 packages/graphiql-react/.storybook/main.ts    |   9 +
 .../graphiql-react/.storybook/preview.tsx     |  64 ++
 packages/graphiql-react/package.json          |   4 +
 .../src/components/operation-editor.tsx       |   3 +-
 .../src/components/response-editor.tsx        |   2 +-
 .../src/components/spinner/spinner.stories.ts |  13 +
 packages/graphiql-react/src/constants.ts      |   2 +-
 packages/graphiql-react/src/index.ts          |   1 +
 .../graphiql-react/src/stores/execution.ts    |   3 +-
 .../src/utility/create-editor.ts              |   2 +-
 packages/graphiql-react/src/utility/index.ts  |   1 -
 yarn.lock                                     | 775 ++++++++++++++++--
 14 files changed, 816 insertions(+), 67 deletions(-)
 create mode 100644 packages/graphiql-react/.storybook/main.ts
 create mode 100644 packages/graphiql-react/.storybook/preview.tsx
 create mode 100644 packages/graphiql-react/src/components/spinner/spinner.stories.ts

diff --git a/.gitignore b/.gitignore
index 8f0b981fff2..38f3fb5120e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -53,3 +53,5 @@ packages/graphiql/typedoc/
 packages/graphiql/webpack/
 
 .react-router/
+
+storybook-static/
diff --git a/package.json b/package.json
index 63384736e7a..8a6457ac212 100644
--- a/package.json
+++ b/package.json
@@ -22,6 +22,8 @@
     "dev:graphiql": "turbo run dev --filter=graphiql...",
     "dev:example-nextjs": "turbo run dev --filter=example-graphiql-nextjs...",
     "dev:example-vite": "turbo run dev --filter=example-graphiql-vite...",
+    "storybook": "yarn workspace @graphiql/react storybook",
+    "build-storybook": "yarn workspace @graphiql/react build-storybook",
     "build:graphiql": "turbo run build --filter=graphiql...",
     "build": "yarn build-clean && yarn build:tsc && yarn build:nontsc",
     "build-bundles": "yarn prebuild-bundles && yarn wsrun:noexamples --stages build-bundles",
diff --git a/packages/graphiql-react/.storybook/main.ts b/packages/graphiql-react/.storybook/main.ts
new file mode 100644
index 00000000000..cf7d1305e8a
--- /dev/null
+++ b/packages/graphiql-react/.storybook/main.ts
@@ -0,0 +1,9 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: [],
+  framework: { name: '@storybook/react-vite', options: {} },
+};
+
+export default config;
diff --git a/packages/graphiql-react/.storybook/preview.tsx b/packages/graphiql-react/.storybook/preview.tsx
new file mode 100644
index 00000000000..2c975d64305
--- /dev/null
+++ b/packages/graphiql-react/.storybook/preview.tsx
@@ -0,0 +1,64 @@
+import type { Preview } from '@storybook/react-vite';
+import '../src/style/root.css';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: { disable: true },
+  },
+  globalTypes: {
+    theme: {
+      description: 'Theme',
+      defaultValue: 'dark',
+      toolbar: {
+        icon: 'circlehollow',
+        items: [
+          { value: 'dark', title: 'Dark' },
+          { value: 'light', title: 'Light' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+    density: {
+      description: 'Density',
+      defaultValue: 'comfortable',
+      toolbar: {
+        icon: 'expand',
+        items: [
+          { value: 'compact', title: 'Compact' },
+          { value: 'comfortable', title: 'Comfortable' },
+          { value: 'spacious', title: 'Spacious' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+    fontSize: {
+      description: 'Font size',
+      defaultValue: 'default',
+      toolbar: {
+        icon: 'beaker',
+        items: [
+          { value: 'compact', title: 'Compact' },
+          { value: 'default', title: 'Default' },
+          { value: 'large', title: 'Large' },
+          { value: 'xl', title: 'Extra large' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [
+    (Story, ctx) => (
+      <div
+        className="graphiql-container"
+        data-theme={ctx.globals.theme}
+        data-density={ctx.globals.density}
+        data-font-size={ctx.globals.fontSize}
+        style={{ padding: 24 }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default preview;
diff --git a/packages/graphiql-react/package.json b/packages/graphiql-react/package.json
index bf9d9dcbd99..dadd8ed9108 100644
--- a/packages/graphiql-react/package.json
+++ b/packages/graphiql-react/package.json
@@ -42,6 +42,8 @@
     "types:check": "tsc --noEmit",
     "dev": "vite build --watch --emptyOutDir=false",
     "build": "vite build",
+    "build-storybook": "storybook build",
+    "storybook": "storybook dev -p 6006",
     "test": "vitest run --typecheck"
   },
   "peerDependencies": {
@@ -70,6 +72,7 @@
   },
   "devDependencies": {
     "@babel/helper-string-parser": "^7.19.4",
+    "@storybook/react-vite": "^10.3.6",
     "@types/get-value": "^3.0.5",
     "@types/markdown-it": "^14.1.2",
     "@types/react-dom": "^19.1.2",
@@ -79,6 +82,7 @@
     "graphql": "^16.9.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "storybook": "^10.3.6",
     "typescript": "^5.8.0",
     "vite": "^6.3.4",
     "vite-plugin-dts": "^4.5.3",
diff --git a/packages/graphiql-react/src/components/operation-editor.tsx b/packages/graphiql-react/src/components/operation-editor.tsx
index 4dfd7ac4226..1cf5a021294 100644
--- a/packages/graphiql-react/src/components/operation-editor.tsx
+++ b/packages/graphiql-react/src/components/operation-editor.tsx
@@ -15,9 +15,8 @@ import {
   pick,
   cleanupDisposables,
   cn,
-  Uri,
-  Range,
 } from '../utility';
+import { Uri, Range } from '../utility/monaco-ssr';
 import type { MonacoEditor, EditorProps, SchemaReference } from '../types';
 import {
   KEY_BINDINGS,
diff --git a/packages/graphiql-react/src/components/response-editor.tsx b/packages/graphiql-react/src/components/response-editor.tsx
index 4cc32990e16..eaff718bee3 100644
--- a/packages/graphiql-react/src/components/response-editor.tsx
+++ b/packages/graphiql-react/src/components/response-editor.tsx
@@ -10,8 +10,8 @@ import {
   pick,
   cleanupDisposables,
   cn,
-  Range,
 } from '../utility';
+import { Range } from '../utility/monaco-ssr';
 import { KEY_BINDINGS, URI_NAME } from '../constants';
 import type { EditorProps } from '../types';
 import type * as monaco from 'monaco-editor';
diff --git a/packages/graphiql-react/src/components/spinner/spinner.stories.ts b/packages/graphiql-react/src/components/spinner/spinner.stories.ts
new file mode 100644
index 00000000000..3f6ca7caf13
--- /dev/null
+++ b/packages/graphiql-react/src/components/spinner/spinner.stories.ts
@@ -0,0 +1,13 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Spinner } from './';
+
+const meta = {
+  title: 'Primitives/Spinner',
+  component: Spinner,
+} satisfies Meta<typeof Spinner>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
diff --git a/packages/graphiql-react/src/constants.ts b/packages/graphiql-react/src/constants.ts
index 996f5724fd2..18b8c25fb8c 100644
--- a/packages/graphiql-react/src/constants.ts
+++ b/packages/graphiql-react/src/constants.ts
@@ -1,7 +1,7 @@
 /* eslint-disable no-bitwise */
 import type { DiagnosticSettings } from 'monaco-graphql';
 import type * as monaco from 'monaco-editor';
-import { KeyCode, KeyMod } from './utility';
+import { KeyCode, KeyMod } from './utility/monaco-ssr';
 import type { EditorSlice } from './stores';
 
 export const isMacOs =
diff --git a/packages/graphiql-react/src/index.ts b/packages/graphiql-react/src/index.ts
index d7a4b2cfe49..314b81a7a3c 100644
--- a/packages/graphiql-react/src/index.ts
+++ b/packages/graphiql-react/src/index.ts
@@ -2,6 +2,7 @@ import './style/root.css';
 
 export { useMonaco } from './stores';
 export * from './utility';
+export { Uri, KeyMod, KeyCode, Range } from './utility/monaco-ssr';
 export type { TabsState } from './utility/tabs';
 export * from './icons';
 export * from './components';
diff --git a/packages/graphiql-react/src/stores/execution.ts b/packages/graphiql-react/src/stores/execution.ts
index 5020b2a3db5..824d933656b 100644
--- a/packages/graphiql-react/src/stores/execution.ts
+++ b/packages/graphiql-react/src/stores/execution.ts
@@ -14,7 +14,8 @@ import setValue from 'set-value';
 import getValue from 'get-value';
 
 import type { StateCreator } from 'zustand';
-import { tryParseJSONC, Range } from '../utility';
+import { tryParseJSONC } from '../utility';
+import { Range } from '../utility/monaco-ssr';
 import type { SlicesWithActions, MonacoEditor } from '../types';
 
 export interface ExecutionSlice {
diff --git a/packages/graphiql-react/src/utility/create-editor.ts b/packages/graphiql-react/src/utility/create-editor.ts
index d2623804030..a480294cafd 100644
--- a/packages/graphiql-react/src/utility/create-editor.ts
+++ b/packages/graphiql-react/src/utility/create-editor.ts
@@ -2,7 +2,7 @@ import type { KeyboardEventHandler, RefObject } from 'react';
 import type * as monaco from 'monaco-editor';
 import type { MonacoEditor } from '../types';
 import { monacoStore } from '../stores';
-import { Uri } from '../utility';
+import { Uri } from './monaco-ssr';
 
 export const onEditorContainerKeyDown: KeyboardEventHandler<
   HTMLDivElement
diff --git a/packages/graphiql-react/src/utility/index.ts b/packages/graphiql-react/src/utility/index.ts
index b1cbca2a325..2090463161a 100644
--- a/packages/graphiql-react/src/utility/index.ts
+++ b/packages/graphiql-react/src/utility/index.ts
@@ -8,7 +8,6 @@ export {
 export { debounce } from './debounce';
 export { formatJSONC, parseJSONC, tryParseJSONC } from './jsonc';
 export { markdown } from './markdown';
-export { Uri, KeyMod, KeyCode, Range } from './monaco-ssr';
 export { pick } from './pick';
 export { useDragResize } from './resize';
 export { clsx as cn } from 'clsx';
diff --git a/yarn.lock b/yarn.lock
index 25a24f35a1e..d6c319f31fb 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1577,7 +1577,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@babel/types@npm:^7.0.0, @babel/types@npm:^7.16.8, @babel/types@npm:^7.20.7, @babel/types@npm:^7.21.3, @babel/types@npm:^7.23.5, @babel/types@npm:^7.23.6, @babel/types@npm:^7.26.0, @babel/types@npm:^7.27.0, @babel/types@npm:^7.27.1, @babel/types@npm:^7.27.3, @babel/types@npm:^7.27.7, @babel/types@npm:^7.28.5, @babel/types@npm:^7.28.6, @babel/types@npm:^7.29.0, @babel/types@npm:^7.4.4":
+"@babel/types@npm:^7.0.0, @babel/types@npm:^7.16.8, @babel/types@npm:^7.20.7, @babel/types@npm:^7.21.3, @babel/types@npm:^7.23.5, @babel/types@npm:^7.23.6, @babel/types@npm:^7.26.0, @babel/types@npm:^7.27.0, @babel/types@npm:^7.27.1, @babel/types@npm:^7.27.3, @babel/types@npm:^7.27.7, @babel/types@npm:^7.28.2, @babel/types@npm:^7.28.5, @babel/types@npm:^7.28.6, @babel/types@npm:^7.29.0, @babel/types@npm:^7.4.4":
   version: 7.29.0
   resolution: "@babel/types@npm:7.29.0"
   dependencies:
@@ -2434,6 +2434,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/aix-ppc64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/aix-ppc64@npm:0.27.7"
+  conditions: os=aix & cpu=ppc64
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-arm64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/android-arm64@npm:0.18.10"
@@ -2455,6 +2462,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/android-arm64@npm:0.27.7"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-arm@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/android-arm@npm:0.18.10"
@@ -2476,6 +2490,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-arm@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/android-arm@npm:0.27.7"
+  conditions: os=android & cpu=arm
+  languageName: node
+  linkType: hard
+
 "@esbuild/android-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/android-x64@npm:0.18.10"
@@ -2497,6 +2518,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/android-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/android-x64@npm:0.27.7"
+  conditions: os=android & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/darwin-arm64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/darwin-arm64@npm:0.18.10"
@@ -2518,6 +2546,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/darwin-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/darwin-arm64@npm:0.27.7"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/darwin-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/darwin-x64@npm:0.18.10"
@@ -2539,6 +2574,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/darwin-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/darwin-x64@npm:0.27.7"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/freebsd-arm64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/freebsd-arm64@npm:0.18.10"
@@ -2560,6 +2602,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/freebsd-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/freebsd-arm64@npm:0.27.7"
+  conditions: os=freebsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/freebsd-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/freebsd-x64@npm:0.18.10"
@@ -2581,6 +2630,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/freebsd-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/freebsd-x64@npm:0.27.7"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-arm64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-arm64@npm:0.18.10"
@@ -2602,6 +2658,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-arm64@npm:0.27.7"
+  conditions: os=linux & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-arm@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-arm@npm:0.18.10"
@@ -2623,6 +2686,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-arm@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-arm@npm:0.27.7"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-ia32@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-ia32@npm:0.18.10"
@@ -2644,6 +2714,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-ia32@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-ia32@npm:0.27.7"
+  conditions: os=linux & cpu=ia32
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-loong64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-loong64@npm:0.18.10"
@@ -2665,6 +2742,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-loong64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-loong64@npm:0.27.7"
+  conditions: os=linux & cpu=loong64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-mips64el@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-mips64el@npm:0.18.10"
@@ -2686,6 +2770,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-mips64el@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-mips64el@npm:0.27.7"
+  conditions: os=linux & cpu=mips64el
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-ppc64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-ppc64@npm:0.18.10"
@@ -2707,6 +2798,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-ppc64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-ppc64@npm:0.27.7"
+  conditions: os=linux & cpu=ppc64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-riscv64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-riscv64@npm:0.18.10"
@@ -2728,6 +2826,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-riscv64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-riscv64@npm:0.27.7"
+  conditions: os=linux & cpu=riscv64
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-s390x@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-s390x@npm:0.18.10"
@@ -2749,6 +2854,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-s390x@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-s390x@npm:0.27.7"
+  conditions: os=linux & cpu=s390x
+  languageName: node
+  linkType: hard
+
 "@esbuild/linux-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/linux-x64@npm:0.18.10"
@@ -2770,6 +2882,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/linux-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/linux-x64@npm:0.27.7"
+  conditions: os=linux & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/netbsd-arm64@npm:0.25.3":
   version: 0.25.3
   resolution: "@esbuild/netbsd-arm64@npm:0.25.3"
@@ -2777,6 +2896,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/netbsd-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/netbsd-arm64@npm:0.27.7"
+  conditions: os=netbsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/netbsd-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/netbsd-x64@npm:0.18.10"
@@ -2798,6 +2924,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/netbsd-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/netbsd-x64@npm:0.27.7"
+  conditions: os=netbsd & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/openbsd-arm64@npm:0.23.1":
   version: 0.23.1
   resolution: "@esbuild/openbsd-arm64@npm:0.23.1"
@@ -2812,6 +2945,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/openbsd-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/openbsd-arm64@npm:0.27.7"
+  conditions: os=openbsd & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/openbsd-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/openbsd-x64@npm:0.18.10"
@@ -2833,6 +2973,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/openbsd-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/openbsd-x64@npm:0.27.7"
+  conditions: os=openbsd & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@esbuild/openharmony-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/openharmony-arm64@npm:0.27.7"
+  conditions: os=openharmony & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/sunos-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/sunos-x64@npm:0.18.10"
@@ -2854,6 +3008,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/sunos-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/sunos-x64@npm:0.27.7"
+  conditions: os=sunos & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-arm64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/win32-arm64@npm:0.18.10"
@@ -2875,6 +3036,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-arm64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/win32-arm64@npm:0.27.7"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-ia32@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/win32-ia32@npm:0.18.10"
@@ -2896,6 +3064,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-ia32@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/win32-ia32@npm:0.27.7"
+  conditions: os=win32 & cpu=ia32
+  languageName: node
+  linkType: hard
+
 "@esbuild/win32-x64@npm:0.18.10":
   version: 0.18.10
   resolution: "@esbuild/win32-x64@npm:0.18.10"
@@ -2917,6 +3092,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@esbuild/win32-x64@npm:0.27.7":
+  version: 0.27.7
+  resolution: "@esbuild/win32-x64@npm:0.27.7"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@exodus/bytes@npm:^1.11.0, @exodus/bytes@npm:^1.15.0, @exodus/bytes@npm:^1.6.0":
   version: 1.15.0
   resolution: "@exodus/bytes@npm:1.15.0"
@@ -3109,6 +3291,7 @@ __metadata:
     "@radix-ui/react-dropdown-menu": "npm:^2.1"
     "@radix-ui/react-tooltip": "npm:^1.2"
     "@radix-ui/react-visually-hidden": "npm:^1.2"
+    "@storybook/react-vite": "npm:^10.3.6"
     "@types/get-value": "npm:^3.0.5"
     "@types/markdown-it": "npm:^14.1.2"
     "@types/react-dom": "npm:^19.1.2"
@@ -3129,6 +3312,7 @@ __metadata:
     react-compiler-runtime: "npm:19.1.0-rc.1"
     react-dom: "npm:^19.1.0"
     set-value: "npm:^4.1.0"
+    storybook: "npm:^10.3.6"
     typescript: "npm:^5.8.0"
     vite: "npm:^6.3.4"
     vite-plugin-dts: "npm:^4.5.3"
@@ -3832,6 +4016,22 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@joshwooding/vite-plugin-react-docgen-typescript@npm:^0.7.0":
+  version: 0.7.0
+  resolution: "@joshwooding/vite-plugin-react-docgen-typescript@npm:0.7.0"
+  dependencies:
+    glob: "npm:^13.0.1"
+    react-docgen-typescript: "npm:^2.2.2"
+  peerDependencies:
+    typescript: ">= 4.3.x"
+    vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+  peerDependenciesMeta:
+    typescript:
+      optional: true
+  checksum: 10c0/6d1a353e4dd0d9d641beafcf8d5c36805ad7f916ae07b817642033bc85c388f819f92dc94db192117dedfaa5d981ac5ef72911315e3e4bf2fe9e23d8956618e6
+  languageName: node
+  linkType: hard
+
 "@jridgewell/gen-mapping@npm:^0.3.0, @jridgewell/gen-mapping@npm:^0.3.12, @jridgewell/gen-mapping@npm:^0.3.2, @jridgewell/gen-mapping@npm:^0.3.5":
   version: 0.3.12
   resolution: "@jridgewell/gen-mapping@npm:0.3.12"
@@ -3869,10 +4069,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@jridgewell/sourcemap-codec@npm:^1.4.14, @jridgewell/sourcemap-codec@npm:^1.4.15, @jridgewell/sourcemap-codec@npm:^1.5.0":
-  version: 1.5.0
-  resolution: "@jridgewell/sourcemap-codec@npm:1.5.0"
-  checksum: 10c0/2eb864f276eb1096c3c11da3e9bb518f6d9fc0023c78344cdc037abadc725172c70314bdb360f2d4b7bffec7f5d657ce006816bc5d4ecb35e61b66132db00c18
+"@jridgewell/sourcemap-codec@npm:^1.4.14, @jridgewell/sourcemap-codec@npm:^1.4.15, @jridgewell/sourcemap-codec@npm:^1.5.0, @jridgewell/sourcemap-codec@npm:^1.5.5":
+  version: 1.5.5
+  resolution: "@jridgewell/sourcemap-codec@npm:1.5.5"
+  checksum: 10c0/f9e538f302b63c0ebc06eecb1dd9918dd4289ed36147a0ddce35d6ea4d7ebbda243cda7b2213b6a5e1d8087a298d5cf630fb2bd39329cdecb82017023f6081a0
   languageName: node
   linkType: hard
 
@@ -5563,7 +5763,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@rollup/pluginutils@npm:^5.0.1, @rollup/pluginutils@npm:^5.1.3, @rollup/pluginutils@npm:^5.1.4":
+"@rollup/pluginutils@npm:^5.0.1, @rollup/pluginutils@npm:^5.0.2, @rollup/pluginutils@npm:^5.1.3, @rollup/pluginutils@npm:^5.1.4":
   version: 5.3.0
   resolution: "@rollup/pluginutils@npm:5.3.0"
   dependencies:
@@ -5852,6 +6052,113 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@storybook/builder-vite@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/builder-vite@npm:10.3.6"
+  dependencies:
+    "@storybook/csf-plugin": "npm:10.3.6"
+    ts-dedent: "npm:^2.0.0"
+  peerDependencies:
+    storybook: ^10.3.6
+    vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+  checksum: 10c0/f7e5c57362ba8df8dac4f71dc86d4117cd1edfaf2f61a3ecb0d6bece6b37357f1dc0bf135fd27b5552055b47e0fce5ffba67ffeb2fdedbc75fc986997062bf28
+  languageName: node
+  linkType: hard
+
+"@storybook/csf-plugin@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/csf-plugin@npm:10.3.6"
+  dependencies:
+    unplugin: "npm:^2.3.5"
+  peerDependencies:
+    esbuild: "*"
+    rollup: "*"
+    storybook: ^10.3.6
+    vite: "*"
+    webpack: "*"
+  peerDependenciesMeta:
+    esbuild:
+      optional: true
+    rollup:
+      optional: true
+    vite:
+      optional: true
+    webpack:
+      optional: true
+  checksum: 10c0/593fc6b9b6073c9dacd26f595ccb58f1ac28f3ab3cf63bf3d8d6913285765eb9c4fdb3e1c54356804ec8eccdde24f14cfa7af3e528731eb6d7e52266d81c4213
+  languageName: node
+  linkType: hard
+
+"@storybook/global@npm:^5.0.0":
+  version: 5.0.0
+  resolution: "@storybook/global@npm:5.0.0"
+  checksum: 10c0/8f1b61dcdd3a89584540896e659af2ecc700bc740c16909a7be24ac19127ea213324de144a141f7caf8affaed017d064fea0618d453afbe027cf60f54b4a6d0b
+  languageName: node
+  linkType: hard
+
+"@storybook/icons@npm:^2.0.1":
+  version: 2.0.2
+  resolution: "@storybook/icons@npm:2.0.2"
+  peerDependencies:
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+  checksum: 10c0/072486356fc929ba5a1a225a8636f0e50b2019083e86e4d48d55aeeae4b40f17731cd1eea9cf1785c53e5fc4409fa93aeca15dccb96675c8e7ab536b18ba864c
+  languageName: node
+  linkType: hard
+
+"@storybook/react-dom-shim@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/react-dom-shim@npm:10.3.6"
+  peerDependencies:
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    storybook: ^10.3.6
+  checksum: 10c0/60183fc05b0410ca174f215d3271ffbccdc2680bd0704f58dc931cf60e72f497a9f22c00afa868398ad693c7ec633ef619541d4b0611fc2a577fb09609fcc3c7
+  languageName: node
+  linkType: hard
+
+"@storybook/react-vite@npm:^10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/react-vite@npm:10.3.6"
+  dependencies:
+    "@joshwooding/vite-plugin-react-docgen-typescript": "npm:^0.7.0"
+    "@rollup/pluginutils": "npm:^5.0.2"
+    "@storybook/builder-vite": "npm:10.3.6"
+    "@storybook/react": "npm:10.3.6"
+    empathic: "npm:^2.0.0"
+    magic-string: "npm:^0.30.0"
+    react-docgen: "npm:^8.0.0"
+    resolve: "npm:^1.22.8"
+    tsconfig-paths: "npm:^4.2.0"
+  peerDependencies:
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    storybook: ^10.3.6
+    vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+  checksum: 10c0/3b939caf05985f0c6d5049c49b71fd8c7abac1f94f1559cfa135a755f3d94c0ef29bdd8d7f7f68c4676ea66852ed4b43d2e33d18434aa1c72f4aebca928b3e13
+  languageName: node
+  linkType: hard
+
+"@storybook/react@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/react@npm:10.3.6"
+  dependencies:
+    "@storybook/global": "npm:^5.0.0"
+    "@storybook/react-dom-shim": "npm:10.3.6"
+    react-docgen: "npm:^8.0.2"
+    react-docgen-typescript: "npm:^2.2.2"
+  peerDependencies:
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    storybook: ^10.3.6
+    typescript: ">= 4.9.x"
+  peerDependenciesMeta:
+    typescript:
+      optional: true
+  checksum: 10c0/3d3af66105cdca98c537b4bcc3e92f87e3b56d154b24e9b167300e9d5de8a7ba6a5ef3c22203ccb6f4c2f0602a5546273b2b49728aa383ba0f98e66a286647a8
+  languageName: node
+  linkType: hard
+
 "@surma/rollup-plugin-off-main-thread@npm:^2.2.3":
   version: 2.2.3
   resolution: "@surma/rollup-plugin-off-main-thread@npm:2.2.3"
@@ -6053,18 +6360,17 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@testing-library/jest-dom@npm:^6.6.3":
-  version: 6.6.3
-  resolution: "@testing-library/jest-dom@npm:6.6.3"
+"@testing-library/jest-dom@npm:^6.6.3, @testing-library/jest-dom@npm:^6.9.1":
+  version: 6.9.1
+  resolution: "@testing-library/jest-dom@npm:6.9.1"
   dependencies:
     "@adobe/css-tools": "npm:^4.4.0"
     aria-query: "npm:^5.0.0"
-    chalk: "npm:^3.0.0"
     css.escape: "npm:^1.5.1"
     dom-accessibility-api: "npm:^0.6.3"
-    lodash: "npm:^4.17.21"
+    picocolors: "npm:^1.1.1"
     redent: "npm:^3.0.0"
-  checksum: 10c0/5566b6c0b7b0709bc244aec3aa3dc9e5f4663e8fb2b99d8cd456fc07279e59db6076cbf798f9d3099a98fca7ef4cd50e4e1f4c4dec5a60a8fad8d24a638a5bf6
+  checksum: 10c0/4291ebd2f0f38d14cefac142c56c337941775a5807e2a3d6f1a14c2fbd6be76a18e498ed189e95bedc97d9e8cf1738049bc76c85b5bc5e23fae7c9e10f7b3a12
   languageName: node
   linkType: hard
 
@@ -6088,6 +6394,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@testing-library/user-event@npm:^14.6.1":
+  version: 14.6.1
+  resolution: "@testing-library/user-event@npm:14.6.1"
+  peerDependencies:
+    "@testing-library/dom": ">=7.21.4"
+  checksum: 10c0/75fea130a52bf320d35d46ed54f3eec77e71a56911b8b69a3fe29497b0b9947b2dc80d30f04054ad4ce7f577856ae3e5397ea7dff0ef14944d3909784c7a93fe
+  languageName: node
+  linkType: hard
+
 "@types/argparse@npm:1.0.38":
   version: 1.0.38
   resolution: "@types/argparse@npm:1.0.38"
@@ -6134,12 +6449,12 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/babel__traverse@npm:*":
-  version: 7.20.1
-  resolution: "@types/babel__traverse@npm:7.20.1"
+"@types/babel__traverse@npm:*, @types/babel__traverse@npm:^7.20.7":
+  version: 7.28.0
+  resolution: "@types/babel__traverse@npm:7.28.0"
   dependencies:
-    "@babel/types": "npm:^7.20.7"
-  checksum: 10c0/5a6a3a26be090573309527184a31f1b82ef55f3d73d811c15f181d323e471305f2390651a04d49d4cd4ca41bbeabb53c9f7862a8e09eab5a0f8910a6aec6e867
+    "@babel/types": "npm:^7.28.2"
+  checksum: 10c0/b52d7d4e8fc6a9018fe7361c4062c1c190f5778cf2466817cb9ed19d69fbbb54f9a85ffedeb748ed8062d2cf7d4cc088ee739848f47c57740de1c48cbf0d0994
   languageName: node
   linkType: hard
 
@@ -6188,6 +6503,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/chai@npm:^5.2.2":
+  version: 5.2.3
+  resolution: "@types/chai@npm:5.2.3"
+  dependencies:
+    "@types/deep-eql": "npm:*"
+    assertion-error: "npm:^2.0.1"
+  checksum: 10c0/e0ef1de3b6f8045a5e473e867c8565788c444271409d155588504840ad1a53611011f85072188c2833941189400228c1745d78323dac13fcede9c2b28bacfb2f
+  languageName: node
+  linkType: hard
+
 "@types/codemirror@npm:^0.0.90":
   version: 0.0.90
   resolution: "@types/codemirror@npm:0.0.90"
@@ -6232,6 +6557,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/deep-eql@npm:*":
+  version: 4.0.2
+  resolution: "@types/deep-eql@npm:4.0.2"
+  checksum: 10c0/bf3f811843117900d7084b9d0c852da9a044d12eb40e6de73b552598a6843c21291a8a381b0532644574beecd5e3491c5ff3a0365ab86b15d59862c025384844
+  languageName: node
+  linkType: hard
+
+"@types/doctrine@npm:^0.0.9":
+  version: 0.0.9
+  resolution: "@types/doctrine@npm:0.0.9"
+  checksum: 10c0/cdaca493f13c321cf0cacd1973efc0ae74569633145d9e6fc1128f32217a6968c33bea1f858275239fe90c98f3be57ec8f452b416a9ff48b8e8c1098b20fa51c
+  languageName: node
+  linkType: hard
+
 "@types/dotenv@npm:8.2.0":
   version: 8.2.0
   resolution: "@types/dotenv@npm:8.2.0"
@@ -6562,6 +6901,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/resolve@npm:^1.20.2":
+  version: 1.20.6
+  resolution: "@types/resolve@npm:1.20.6"
+  checksum: 10c0/a9b0549d816ff2c353077365d865a33655a141d066d0f5a3ba6fd4b28bc2f4188a510079f7c1f715b3e7af505a27374adce2a5140a3ece2a059aab3d6e1a4244
+  languageName: node
+  linkType: hard
+
 "@types/responselike@npm:^1.0.0":
   version: 1.0.0
   resolution: "@types/responselike@npm:1.0.0"
@@ -6891,6 +7237,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/expect@npm:3.2.4":
+  version: 3.2.4
+  resolution: "@vitest/expect@npm:3.2.4"
+  dependencies:
+    "@types/chai": "npm:^5.2.2"
+    "@vitest/spy": "npm:3.2.4"
+    "@vitest/utils": "npm:3.2.4"
+    chai: "npm:^5.2.0"
+    tinyrainbow: "npm:^2.0.0"
+  checksum: 10c0/7586104e3fd31dbe1e6ecaafb9a70131e4197dce2940f727b6a84131eee3decac7b10f9c7c72fa5edbdb68b6f854353bd4c0fa84779e274207fb7379563b10db
+  languageName: node
+  linkType: hard
+
 "@vitest/mocker@npm:2.1.9":
   version: 2.1.9
   resolution: "@vitest/mocker@npm:2.1.9"
@@ -6919,6 +7278,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/pretty-format@npm:3.2.4":
+  version: 3.2.4
+  resolution: "@vitest/pretty-format@npm:3.2.4"
+  dependencies:
+    tinyrainbow: "npm:^2.0.0"
+  checksum: 10c0/5ad7d4278e067390d7d633e307fee8103958806a419ca380aec0e33fae71b44a64415f7a9b4bc11635d3c13d4a9186111c581d3cef9c65cc317e68f077456887
+  languageName: node
+  linkType: hard
+
 "@vitest/runner@npm:2.1.9":
   version: 2.1.9
   resolution: "@vitest/runner@npm:2.1.9"
@@ -6949,6 +7317,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/spy@npm:3.2.4":
+  version: 3.2.4
+  resolution: "@vitest/spy@npm:3.2.4"
+  dependencies:
+    tinyspy: "npm:^4.0.3"
+  checksum: 10c0/6ebf0b4697dc238476d6b6a60c76ba9eb1dd8167a307e30f08f64149612fd50227682b876420e4c2e09a76334e73f72e3ebf0e350714dc22474258292e202024
+  languageName: node
+  linkType: hard
+
 "@vitest/utils@npm:2.1.9":
   version: 2.1.9
   resolution: "@vitest/utils@npm:2.1.9"
@@ -6960,6 +7337,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/utils@npm:3.2.4":
+  version: 3.2.4
+  resolution: "@vitest/utils@npm:3.2.4"
+  dependencies:
+    "@vitest/pretty-format": "npm:3.2.4"
+    loupe: "npm:^3.1.4"
+    tinyrainbow: "npm:^2.0.0"
+  checksum: 10c0/024a9b8c8bcc12cf40183c246c244b52ecff861c6deb3477cbf487ac8781ad44c68a9c5fd69f8c1361878e55b97c10d99d511f2597f1f7244b5e5101d028ba64
+  languageName: node
+  linkType: hard
+
 "@vitest/web-worker@npm:3.1.4":
   version: 3.1.4
   resolution: "@vitest/web-worker@npm:3.1.4"
@@ -7447,6 +7835,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@webcontainer/env@npm:^1.1.1":
+  version: 1.1.1
+  resolution: "@webcontainer/env@npm:1.1.1"
+  checksum: 10c0/bc64114ffa7ee92f4985cc2bdd5e27f6f31d892b9aa5cde68eaf93df02d13ee6edf13faeebdd701464183b6f8f9c47c14975958cdd6fc20e7356ad32f6ee39e7
+  languageName: node
+  linkType: hard
+
 "@webpack-cli/configtest@npm:^2.1.1":
   version: 2.1.1
   resolution: "@webpack-cli/configtest@npm:2.1.1"
@@ -8145,6 +8540,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ast-types@npm:^0.16.1":
+  version: 0.16.1
+  resolution: "ast-types@npm:0.16.1"
+  dependencies:
+    tslib: "npm:^2.0.1"
+  checksum: 10c0/abcc49e42eb921a7ebc013d5bec1154651fb6dbc3f497541d488859e681256901b2990b954d530ba0da4d0851271d484f7057d5eff5e07cb73e8b10909f711bf
+  languageName: node
+  linkType: hard
+
 "astral-regex@npm:^2.0.0":
   version: 2.0.0
   resolution: "astral-regex@npm:2.0.0"
@@ -8834,16 +9238,16 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chai@npm:^5.1.2":
-  version: 5.1.2
-  resolution: "chai@npm:5.1.2"
+"chai@npm:^5.1.2, chai@npm:^5.2.0":
+  version: 5.3.3
+  resolution: "chai@npm:5.3.3"
   dependencies:
     assertion-error: "npm:^2.0.1"
     check-error: "npm:^2.1.1"
     deep-eql: "npm:^5.0.1"
     loupe: "npm:^3.1.0"
     pathval: "npm:^2.0.0"
-  checksum: 10c0/6c04ff8495b6e535df9c1b062b6b094828454e9a3c9493393e55b2f4dbff7aa2a29a4645133cad160fb00a16196c4dc03dc9bb37e1f4ba9df3b5f50d7533a736
+  checksum: 10c0/b360fd4d38861622e5010c2f709736988b05c7f31042305fa3f4e9911f6adb80ccfb4e302068bf8ed10e835c2e2520cba0f5edc13d878b886987e5aa62483f53
   languageName: node
   linkType: hard
 
@@ -8858,16 +9262,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chalk@npm:^3.0.0":
-  version: 3.0.0
-  resolution: "chalk@npm:3.0.0"
-  dependencies:
-    ansi-styles: "npm:^4.1.0"
-    supports-color: "npm:^7.1.0"
-  checksum: 10c0/ee650b0a065b3d7a6fda258e75d3a86fc8e4effa55871da730a9e42ccb035bf5fd203525e5a1ef45ec2582ecc4f65b47eb11357c526b84dd29a14fb162c414d2
-  languageName: node
-  linkType: hard
-
 "chalk@npm:^4.0.2, chalk@npm:^4.1.0, chalk@npm:^4.1.2":
   version: 4.1.2
   resolution: "chalk@npm:4.1.2"
@@ -10412,6 +10806,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"doctrine@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "doctrine@npm:3.0.0"
+  dependencies:
+    esutils: "npm:^2.0.2"
+  checksum: 10c0/c96bdccabe9d62ab6fea9399fdff04a66e6563c1d6fb3a3a063e8d53c3bb136ba63e84250bbf63d00086a769ad53aef92d2bd483f03f837fc97b71cbee6b2520
+  languageName: node
+  linkType: hard
+
 "dom-accessibility-api@npm:^0.5.9":
   version: 0.5.16
   resolution: "dom-accessibility-api@npm:0.5.16"
@@ -10655,6 +11058,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"empathic@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "empathic@npm:2.0.1"
+  checksum: 10c0/577f2868bfcad4ffbf911b57c75016125eb8cc8a7d32cf2d3e9fbcb31bfe6e9e6b66d9457ac34ccb2cd38bff353b3af34287899e0360b8c561ff6d4a048aca62
+  languageName: node
+  linkType: hard
+
 "encodeurl@npm:~2.0.0":
   version: 2.0.0
   resolution: "encodeurl@npm:2.0.0"
@@ -10948,6 +11358,95 @@ __metadata:
   languageName: node
   linkType: hard
 
+"esbuild@npm:^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0":
+  version: 0.27.7
+  resolution: "esbuild@npm:0.27.7"
+  dependencies:
+    "@esbuild/aix-ppc64": "npm:0.27.7"
+    "@esbuild/android-arm": "npm:0.27.7"
+    "@esbuild/android-arm64": "npm:0.27.7"
+    "@esbuild/android-x64": "npm:0.27.7"
+    "@esbuild/darwin-arm64": "npm:0.27.7"
+    "@esbuild/darwin-x64": "npm:0.27.7"
+    "@esbuild/freebsd-arm64": "npm:0.27.7"
+    "@esbuild/freebsd-x64": "npm:0.27.7"
+    "@esbuild/linux-arm": "npm:0.27.7"
+    "@esbuild/linux-arm64": "npm:0.27.7"
+    "@esbuild/linux-ia32": "npm:0.27.7"
+    "@esbuild/linux-loong64": "npm:0.27.7"
+    "@esbuild/linux-mips64el": "npm:0.27.7"
+    "@esbuild/linux-ppc64": "npm:0.27.7"
+    "@esbuild/linux-riscv64": "npm:0.27.7"
+    "@esbuild/linux-s390x": "npm:0.27.7"
+    "@esbuild/linux-x64": "npm:0.27.7"
+    "@esbuild/netbsd-arm64": "npm:0.27.7"
+    "@esbuild/netbsd-x64": "npm:0.27.7"
+    "@esbuild/openbsd-arm64": "npm:0.27.7"
+    "@esbuild/openbsd-x64": "npm:0.27.7"
+    "@esbuild/openharmony-arm64": "npm:0.27.7"
+    "@esbuild/sunos-x64": "npm:0.27.7"
+    "@esbuild/win32-arm64": "npm:0.27.7"
+    "@esbuild/win32-ia32": "npm:0.27.7"
+    "@esbuild/win32-x64": "npm:0.27.7"
+  dependenciesMeta:
+    "@esbuild/aix-ppc64":
+      optional: true
+    "@esbuild/android-arm":
+      optional: true
+    "@esbuild/android-arm64":
+      optional: true
+    "@esbuild/android-x64":
+      optional: true
+    "@esbuild/darwin-arm64":
+      optional: true
+    "@esbuild/darwin-x64":
+      optional: true
+    "@esbuild/freebsd-arm64":
+      optional: true
+    "@esbuild/freebsd-x64":
+      optional: true
+    "@esbuild/linux-arm":
+      optional: true
+    "@esbuild/linux-arm64":
+      optional: true
+    "@esbuild/linux-ia32":
+      optional: true
+    "@esbuild/linux-loong64":
+      optional: true
+    "@esbuild/linux-mips64el":
+      optional: true
+    "@esbuild/linux-ppc64":
+      optional: true
+    "@esbuild/linux-riscv64":
+      optional: true
+    "@esbuild/linux-s390x":
+      optional: true
+    "@esbuild/linux-x64":
+      optional: true
+    "@esbuild/netbsd-arm64":
+      optional: true
+    "@esbuild/netbsd-x64":
+      optional: true
+    "@esbuild/openbsd-arm64":
+      optional: true
+    "@esbuild/openbsd-x64":
+      optional: true
+    "@esbuild/openharmony-arm64":
+      optional: true
+    "@esbuild/sunos-x64":
+      optional: true
+    "@esbuild/win32-arm64":
+      optional: true
+    "@esbuild/win32-ia32":
+      optional: true
+    "@esbuild/win32-x64":
+      optional: true
+  bin:
+    esbuild: bin/esbuild
+  checksum: 10c0/ccd51f0555708bc9ff4ec9dc3ac92d3daacd45ecaac949ca8645984c5c323bf8cefe98c2df307418685e0b4ce37f9a3bdbfe8e3651fe632a0059a436195a17d4
+  languageName: node
+  linkType: hard
+
 "esbuild@npm:^0.23.0":
   version: 0.23.1
   resolution: "esbuild@npm:0.23.1"
@@ -11185,7 +11684,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"esprima@npm:^4.0.0, esprima@npm:^4.0.1":
+"esprima@npm:^4.0.0, esprima@npm:^4.0.1, esprima@npm:~4.0.0":
   version: 4.0.1
   resolution: "esprima@npm:4.0.1"
   bin:
@@ -12724,6 +13223,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"glob@npm:^13.0.1":
+  version: 13.0.6
+  resolution: "glob@npm:13.0.6"
+  dependencies:
+    minimatch: "npm:^10.2.2"
+    minipass: "npm:^7.1.3"
+    path-scurry: "npm:^2.0.2"
+  checksum: 10c0/269c236f11a9b50357fe7a8c6aadac667e01deb5242b19c84975628f05f4438d8ee1354bb62c5d6c10f37fd59911b54d7799730633a2786660d8c69f1d18120a
+  languageName: node
+  linkType: hard
+
 "glob@npm:^7.0.5, glob@npm:^7.0.6, glob@npm:^7.1.2, glob@npm:^7.1.3, glob@npm:^7.2.0":
   version: 7.2.3
   resolution: "glob@npm:7.2.3"
@@ -14777,7 +15287,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"json5@npm:^2.1.2, json5@npm:^2.2.0, json5@npm:^2.2.3":
+"json5@npm:^2.1.2, json5@npm:^2.2.0, json5@npm:^2.2.2, json5@npm:^2.2.3":
   version: 2.2.3
   resolution: "json5@npm:2.2.3"
   bin:
@@ -15401,10 +15911,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"loupe@npm:^3.1.0, loupe@npm:^3.1.2":
-  version: 3.1.2
-  resolution: "loupe@npm:3.1.2"
-  checksum: 10c0/b13c02e3ddd6a9d5f8bf84133b3242de556512d824dddeea71cce2dbd6579c8f4d672381c4e742d45cf4423d0701765b4a6e5fbc24701def16bc2b40f8daa96a
+"loupe@npm:^3.1.0, loupe@npm:^3.1.2, loupe@npm:^3.1.4":
+  version: 3.2.1
+  resolution: "loupe@npm:3.2.1"
+  checksum: 10c0/910c872cba291309664c2d094368d31a68907b6f5913e989d301b5c25f30e97d76d77f23ab3bf3b46d0f601ff0b6af8810c10c31b91d2c6b2f132809ca2cc705
   languageName: node
   linkType: hard
 
@@ -15491,12 +16001,12 @@ __metadata:
   languageName: node
   linkType: hard
 
-"magic-string@npm:^0.30.10, magic-string@npm:^0.30.12, magic-string@npm:^0.30.17, magic-string@npm:^0.30.4":
-  version: 0.30.17
-  resolution: "magic-string@npm:0.30.17"
+"magic-string@npm:^0.30.0, magic-string@npm:^0.30.10, magic-string@npm:^0.30.12, magic-string@npm:^0.30.17, magic-string@npm:^0.30.4":
+  version: 0.30.21
+  resolution: "magic-string@npm:0.30.21"
   dependencies:
-    "@jridgewell/sourcemap-codec": "npm:^1.5.0"
-  checksum: 10c0/16826e415d04b88378f200fe022b53e638e3838b9e496edda6c0e086d7753a44a6ed187adc72d19f3623810589bf139af1a315541cd6a26ae0771a0193eaf7b8
+    "@jridgewell/sourcemap-codec": "npm:^1.5.5"
+  checksum: 10c0/299378e38f9a270069fc62358522ddfb44e94244baa0d6a8980ab2a9b2490a1d03b236b447eee309e17eb3bddfa482c61259d47960eb018a904f0ded52780c4a
   languageName: node
   linkType: hard
 
@@ -15868,7 +16378,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minimatch@npm:^10.0.0, minimatch@npm:^10.1.1, minimatch@npm:^10.2.5":
+"minimatch@npm:^10.0.0, minimatch@npm:^10.1.1, minimatch@npm:^10.2.2, minimatch@npm:^10.2.5":
   version: 10.2.5
   resolution: "minimatch@npm:10.2.5"
   dependencies:
@@ -15991,10 +16501,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2":
-  version: 7.1.2
-  resolution: "minipass@npm:7.1.2"
-  checksum: 10c0/b0fd20bb9fb56e5fa9a8bfac539e8915ae07430a619e4b86ff71f5fc757ef3924b23b2c4230393af1eda647ed3d75739e4e0acb250a6b1eb277cf7f8fe449557
+"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2, minipass@npm:^7.1.3":
+  version: 7.1.3
+  resolution: "minipass@npm:7.1.3"
+  checksum: 10c0/539da88daca16533211ea5a9ee98dc62ff5742f531f54640dd34429e621955e91cc280a91a776026264b7f9f6735947629f920944e9c1558369e8bf22eb33fbb
   languageName: node
   linkType: hard
 
@@ -16741,15 +17251,15 @@ __metadata:
   languageName: node
   linkType: hard
 
-"open@npm:^10.0.3":
-  version: 10.1.2
-  resolution: "open@npm:10.1.2"
+"open@npm:^10.0.3, open@npm:^10.2.0":
+  version: 10.2.0
+  resolution: "open@npm:10.2.0"
   dependencies:
     default-browser: "npm:^5.2.1"
     define-lazy-prop: "npm:^3.0.0"
     is-inside-container: "npm:^1.0.0"
-    is-wsl: "npm:^3.1.0"
-  checksum: 10c0/1bee796f06e549ce764f693272100323fbc04da8fa3c5b0402d6c2d11b3d76fa0aac0be7535e710015ff035326638e3b9a563f3b0e7ac3266473ed5663caae6d
+    wsl-utils: "npm:^0.1.0"
+  checksum: 10c0/5a36d0c1fd2f74ce553beb427ca8b8494b623fc22c6132d0c1688f246a375e24584ea0b44c67133d9ab774fa69be8e12fbe1ff12504b1142bd960fb09671948f
   languageName: node
   linkType: hard
 
@@ -17398,7 +17908,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"path-scurry@npm:^2.0.0":
+"path-scurry@npm:^2.0.0, path-scurry@npm:^2.0.2":
   version: 2.0.2
   resolution: "path-scurry@npm:2.0.2"
   dependencies:
@@ -17505,10 +18015,10 @@ __metadata:
   languageName: node
   linkType: hard
 
-"picomatch@npm:^4.0.2":
-  version: 4.0.2
-  resolution: "picomatch@npm:4.0.2"
-  checksum: 10c0/7c51f3ad2bb42c776f49ebf964c644958158be30d0a510efd5a395e8d49cb5acfed5b82c0c5b365523ce18e6ab85013c9ebe574f60305892ec3fa8eee8304ccc
+"picomatch@npm:^4.0.2, picomatch@npm:^4.0.3":
+  version: 4.0.4
+  resolution: "picomatch@npm:4.0.4"
+  checksum: 10c0/e2c6023372cc7b5764719a5ffb9da0f8e781212fa7ca4bd0562db929df8e117460f00dff3cb7509dacfc06b86de924b247f504d0ce1806a37fac4633081466b0
   languageName: node
   linkType: hard
 
@@ -18059,6 +18569,33 @@ __metadata:
   languageName: node
   linkType: hard
 
+"react-docgen-typescript@npm:^2.2.2":
+  version: 2.4.0
+  resolution: "react-docgen-typescript@npm:2.4.0"
+  peerDependencies:
+    typescript: ">= 4.3.x"
+  checksum: 10c0/18e3e1c80d28abcdd72e62261d2f70b0904d9b088f9c2ebe485ffee5e46f5735208bc174a20ed2772112b3ca6432b5f3d5f0ac345872fe76e541f84543e49e50
+  languageName: node
+  linkType: hard
+
+"react-docgen@npm:^8.0.0, react-docgen@npm:^8.0.2":
+  version: 8.0.3
+  resolution: "react-docgen@npm:8.0.3"
+  dependencies:
+    "@babel/core": "npm:^7.28.0"
+    "@babel/traverse": "npm:^7.28.0"
+    "@babel/types": "npm:^7.28.2"
+    "@types/babel__core": "npm:^7.20.5"
+    "@types/babel__traverse": "npm:^7.20.7"
+    "@types/doctrine": "npm:^0.0.9"
+    "@types/resolve": "npm:^1.20.2"
+    doctrine: "npm:^3.0.0"
+    resolve: "npm:^1.22.1"
+    strip-indent: "npm:^4.0.0"
+  checksum: 10c0/0231fb9177bc7c633f3d1f228eebb0ee90a2f0feac50b1869ef70b0a3683b400d7875547a2d5168f2619b63d4cc29d7c45ae33d3f621fc67a7fa6790ac2049f6
+  languageName: node
+  linkType: hard
+
 "react-dom@npm:18.3.1":
   version: 18.3.1
   resolution: "react-dom@npm:18.3.1"
@@ -18291,6 +18828,19 @@ __metadata:
   languageName: node
   linkType: hard
 
+"recast@npm:^0.23.5":
+  version: 0.23.11
+  resolution: "recast@npm:0.23.11"
+  dependencies:
+    ast-types: "npm:^0.16.1"
+    esprima: "npm:~4.0.0"
+    source-map: "npm:~0.6.1"
+    tiny-invariant: "npm:^1.3.3"
+    tslib: "npm:^2.0.1"
+  checksum: 10c0/45b520a8f0868a5a24ecde495be9de3c48e69a54295d82a7331106554b75cfba75d16c909959d056e9ceed47a1be5e061e2db8b9ecbcd6ba44c2f3ef9a47bd18
+  languageName: node
+  linkType: hard
+
 "rechoir@npm:^0.8.0":
   version: 0.8.0
   resolution: "rechoir@npm:0.8.0"
@@ -18570,7 +19120,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"resolve@npm:^1.10.0, resolve@npm:^1.15.1, resolve@npm:^1.19.0, resolve@npm:^1.20.0, resolve@npm:^1.22.1, resolve@npm:^1.22.11, resolve@npm:~1.22.1, resolve@npm:~1.22.2":
+"resolve@npm:^1.10.0, resolve@npm:^1.15.1, resolve@npm:^1.19.0, resolve@npm:^1.20.0, resolve@npm:^1.22.1, resolve@npm:^1.22.11, resolve@npm:^1.22.8, resolve@npm:~1.22.1, resolve@npm:~1.22.2":
   version: 1.22.12
   resolution: "resolve@npm:1.22.12"
   dependencies:
@@ -18584,7 +19134,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"resolve@patch:resolve@npm%3A^1.10.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.15.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.19.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.20.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.22.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.22.11#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A~1.22.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A~1.22.2#optional!builtin<compat/resolve>":
+"resolve@patch:resolve@npm%3A^1.10.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.15.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.19.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.20.0#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.22.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.22.11#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A^1.22.8#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A~1.22.1#optional!builtin<compat/resolve>, resolve@patch:resolve@npm%3A~1.22.2#optional!builtin<compat/resolve>":
   version: 1.22.12
   resolution: "resolve@patch:resolve@npm%3A1.22.12#optional!builtin<compat/resolve>::version=1.22.12&hash=c3c19d"
   dependencies:
@@ -19786,6 +20336,37 @@ __metadata:
   languageName: node
   linkType: hard
 
+"storybook@npm:^10.3.6":
+  version: 10.3.6
+  resolution: "storybook@npm:10.3.6"
+  dependencies:
+    "@storybook/global": "npm:^5.0.0"
+    "@storybook/icons": "npm:^2.0.1"
+    "@testing-library/jest-dom": "npm:^6.9.1"
+    "@testing-library/user-event": "npm:^14.6.1"
+    "@vitest/expect": "npm:3.2.4"
+    "@vitest/spy": "npm:3.2.4"
+    "@webcontainer/env": "npm:^1.1.1"
+    esbuild: "npm:^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0"
+    open: "npm:^10.2.0"
+    recast: "npm:^0.23.5"
+    semver: "npm:^7.7.3"
+    use-sync-external-store: "npm:^1.5.0"
+    ws: "npm:^8.18.0"
+  peerDependencies:
+    prettier: ^2 || ^3
+    vite-plus: ^0.1.15
+  peerDependenciesMeta:
+    prettier:
+      optional: true
+    vite-plus:
+      optional: true
+  bin:
+    storybook: ./dist/bin/dispatcher.js
+  checksum: 10c0/ee6702667459ba2d49269ddd63a7281f17816fcdd4bacd338ed47a4a8e7ad65760c90d99f6b2dfdfd0a564bcfcab3c1ea05b50bf3aafc6b5b19a039a5da77870
+  languageName: node
+  linkType: hard
+
 "stream-combiner@npm:~0.0.4":
   version: 0.0.4
   resolution: "stream-combiner@npm:0.0.4"
@@ -20071,6 +20652,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"strip-indent@npm:^4.0.0":
+  version: 4.1.1
+  resolution: "strip-indent@npm:4.1.1"
+  checksum: 10c0/5b23dd5934be0ef6b6fe1b802887f83e56ad9dcd9f6c3896a637da2c6c3a6da3fdf3e51354a98e6cccb6f1c41863e7b9b9deaa348639dfd35f71f3549edb4dff
+  languageName: node
+  linkType: hard
+
 "strip-json-comments@npm:3.1.1, strip-json-comments@npm:^3.0.0, strip-json-comments@npm:~3.1.1":
   version: 3.1.1
   resolution: "strip-json-comments@npm:3.1.1"
@@ -20493,6 +21081,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tiny-invariant@npm:^1.3.3":
+  version: 1.3.3
+  resolution: "tiny-invariant@npm:1.3.3"
+  checksum: 10c0/65af4a07324b591a059b35269cd696aba21bef2107f29b9f5894d83cc143159a204b299553435b03874ebb5b94d019afa8b8eff241c8a4cfee95872c2e1c1c4a
+  languageName: node
+  linkType: hard
+
 "tinybench@npm:^2.9.0":
   version: 2.9.0
   resolution: "tinybench@npm:2.9.0"
@@ -20538,6 +21133,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinyrainbow@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "tinyrainbow@npm:2.0.0"
+  checksum: 10c0/c83c52bef4e0ae7fb8ec6a722f70b5b6fa8d8be1c85792e829f56c0e1be94ab70b293c032dc5048d4d37cfe678f1f5babb04bdc65fd123098800148ca989184f
+  languageName: node
+  linkType: hard
+
 "tinyspy@npm:^3.0.2":
   version: 3.0.2
   resolution: "tinyspy@npm:3.0.2"
@@ -20545,6 +21147,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinyspy@npm:^4.0.3":
+  version: 4.0.4
+  resolution: "tinyspy@npm:4.0.4"
+  checksum: 10c0/a8020fc17799251e06a8398dcc352601d2770aa91c556b9531ecd7a12581161fd1c14e81cbdaff0c1306c93bfdde8ff6d1c1a3f9bbe6d91604f0fd4e01e2f1eb
+  languageName: node
+  linkType: hard
+
 "tldts-core@npm:^7.0.28":
   version: 7.0.28
   resolution: "tldts-core@npm:7.0.28"
@@ -20712,6 +21321,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ts-dedent@npm:^2.0.0":
+  version: 2.2.0
+  resolution: "ts-dedent@npm:2.2.0"
+  checksum: 10c0/175adea838468cc2ff7d5e97f970dcb798bbcb623f29c6088cb21aa2880d207c5784be81ab1741f56b9ac37840cbaba0c0d79f7f8b67ffe61c02634cafa5c303
+  languageName: node
+  linkType: hard
+
 "ts-interface-checker@npm:^0.1.9":
   version: 0.1.13
   resolution: "ts-interface-checker@npm:0.1.13"
@@ -20739,6 +21355,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tsconfig-paths@npm:^4.2.0":
+  version: 4.2.0
+  resolution: "tsconfig-paths@npm:4.2.0"
+  dependencies:
+    json5: "npm:^2.2.2"
+    minimist: "npm:^1.2.6"
+    strip-bom: "npm:^3.0.0"
+  checksum: 10c0/09a5877402d082bb1134930c10249edeebc0211f36150c35e1c542e5b91f1047b1ccf7da1e59babca1ef1f014c525510f4f870de7c9bda470c73bb4e2721b3ea
+  languageName: node
+  linkType: hard
+
 "tslib@npm:^1.9.0, tslib@npm:^1.9.3":
   version: 1.14.1
   resolution: "tslib@npm:1.14.1"
@@ -20746,7 +21373,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"tslib@npm:^2.0.0, tslib@npm:^2.0.3, tslib@npm:^2.1.0, tslib@npm:^2.2.0, tslib@npm:^2.4.0, tslib@npm:^2.5.0, tslib@npm:^2.6.2, tslib@npm:^2.6.3, tslib@npm:^2.8.0, tslib@npm:^2.8.1":
+"tslib@npm:^2.0.0, tslib@npm:^2.0.1, tslib@npm:^2.0.3, tslib@npm:^2.1.0, tslib@npm:^2.2.0, tslib@npm:^2.4.0, tslib@npm:^2.5.0, tslib@npm:^2.6.2, tslib@npm:^2.6.3, tslib@npm:^2.8.0, tslib@npm:^2.8.1":
   version: 2.8.1
   resolution: "tslib@npm:2.8.1"
   checksum: 10c0/9c4759110a19c53f992d9aae23aac5ced636e99887b51b9e61def52611732872ff7668757d4e4c61f19691e36f4da981cd9485e869b4a7408d689f6bf1f14e62
@@ -21266,6 +21893,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"unplugin@npm:^2.3.5":
+  version: 2.3.11
+  resolution: "unplugin@npm:2.3.11"
+  dependencies:
+    "@jridgewell/remapping": "npm:^2.3.5"
+    acorn: "npm:^8.15.0"
+    picomatch: "npm:^4.0.3"
+    webpack-virtual-modules: "npm:^0.6.2"
+  checksum: 10c0/273c1eab0eca4470c7317428689295c31dbe8ab0b306504de9f03cd20c156debb4131bef24b27ac615862958c5dd950a3951d26c0723ea774652ab3624149cff
+  languageName: node
+  linkType: hard
+
 "until-async@npm:^3.0.2":
   version: 3.0.2
   resolution: "until-async@npm:3.0.2"
@@ -22138,6 +22777,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"webpack-virtual-modules@npm:^0.6.2":
+  version: 0.6.2
+  resolution: "webpack-virtual-modules@npm:0.6.2"
+  checksum: 10c0/5ffbddf0e84bf1562ff86cf6fcf039c74edf09d78358a6904a09bbd4484e8bb6812dc385fe14330b715031892dcd8423f7a88278b57c9f5002c84c2860179add
+  languageName: node
+  linkType: hard
+
 "webpack@npm:^5":
   version: 5.106.2
   resolution: "webpack@npm:5.106.2"
@@ -22748,6 +23394,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"wsl-utils@npm:^0.1.0":
+  version: 0.1.0
+  resolution: "wsl-utils@npm:0.1.0"
+  dependencies:
+    is-wsl: "npm:^3.1.0"
+  checksum: 10c0/44318f3585eb97be994fc21a20ddab2649feaf1fbe893f1f866d936eea3d5f8c743bec6dc02e49fbdd3c0e69e9b36f449d90a0b165a4f47dd089747af4cf2377
+  languageName: node
+  linkType: hard
+
 "wsrun@npm:^5.2.4":
   version: 5.2.4
   resolution: "wsrun@npm:5.2.4"

From 53054cd5b22519c7ddeb2214a6d4330d03878b1b Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 14 May 2026 13:18:04 -0700
Subject: [PATCH 06/38] v6: Add `cypress-axe` for full-app a11y coverage
 (#4258)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Component a11y is covered by Storybook + axe; this is the full-app
counterpart. `cypress-axe` runs axe at four checkpoints during a normal
session (initial render, after running a query, with the docs panel
open, with the history panel open) and gates PRs against a committed
baseline.

`cypress/.a11y-baseline.json` pins today's accepted violations —
color-contrast in several spots, a couple of nested-interactive cases,
link-in-text-block in the docs panel. CI fails on net-new only.

The spec lives alongside the existing Cypress suite, so it runs as part
of the normal `yarn e2e` flow. `cypress.config.ts` gets a small
`writeBaseline` Node task so the spec can persist baseline updates from
inside the browser.

## Refresh baseline

```
yarn workspace graphiql test:a11y:update
```

Refs: graphql/graphiql#4219
---
 packages/graphiql/cypress.config.ts           |  17 +
 packages/graphiql/cypress/.a11y-baseline.json |  55 ++
 packages/graphiql/cypress/e2e/a11y.cy.ts      | 104 +++
 packages/graphiql/cypress/support/e2e.ts      |   1 +
 packages/graphiql/cypress/tsconfig.json       |   4 +-
 packages/graphiql/package.json                |   3 +
 resources/custom-words.txt                    |   2 +
 yarn.lock                                     | 657 ++----------------
 8 files changed, 247 insertions(+), 596 deletions(-)
 create mode 100644 packages/graphiql/cypress/.a11y-baseline.json
 create mode 100644 packages/graphiql/cypress/e2e/a11y.cy.ts

diff --git a/packages/graphiql/cypress.config.ts b/packages/graphiql/cypress.config.ts
index e48832c01c7..6df53e90f35 100644
--- a/packages/graphiql/cypress.config.ts
+++ b/packages/graphiql/cypress.config.ts
@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import path from 'node:path';
 import { defineConfig } from 'cypress';
 
 const PORT = process.env.CI === 'true' ? 8080 : 5173;
@@ -5,6 +7,21 @@ const PORT = process.env.CI === 'true' ? 8080 : 5173;
 export default defineConfig({
   e2e: {
     baseUrl: `http://localhost:${PORT}`,
+    setupNodeEvents(on) {
+      on('task', {
+        writeBaseline({ filePath, data }: { filePath: string; data: unknown }) {
+          const abs = path.isAbsolute(filePath)
+            ? filePath
+            : path.resolve(process.cwd(), filePath);
+          const dir = path.dirname(abs);
+          if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+          }
+          fs.writeFileSync(abs, JSON.stringify(data, null, 2) + '\n');
+          return null;
+        },
+      });
+    },
   },
   video: true,
   viewportWidth: 1920,
diff --git a/packages/graphiql/cypress/.a11y-baseline.json b/packages/graphiql/cypress/.a11y-baseline.json
new file mode 100644
index 00000000000..886cfc1a11d
--- /dev/null
+++ b/packages/graphiql/cypress/.a11y-baseline.json
@@ -0,0 +1,55 @@
+{
+  "initial": [
+    {
+      "id": "color-contrast",
+      "impact": "serious",
+      "nodeCount": 1
+    },
+    {
+      "id": "nested-interactive",
+      "impact": "serious",
+      "nodeCount": 1
+    }
+  ],
+  "post-run": [
+    {
+      "id": "color-contrast",
+      "impact": "serious",
+      "nodeCount": 2
+    },
+    {
+      "id": "nested-interactive",
+      "impact": "serious",
+      "nodeCount": 1
+    }
+  ],
+  "docs-open": [
+    {
+      "id": "color-contrast",
+      "impact": "serious",
+      "nodeCount": 21
+    },
+    {
+      "id": "link-in-text-block",
+      "impact": "serious",
+      "nodeCount": 1
+    },
+    {
+      "id": "nested-interactive",
+      "impact": "serious",
+      "nodeCount": 1
+    }
+  ],
+  "history-open": [
+    {
+      "id": "color-contrast",
+      "impact": "serious",
+      "nodeCount": 1
+    },
+    {
+      "id": "nested-interactive",
+      "impact": "serious",
+      "nodeCount": 1
+    }
+  ]
+}
diff --git a/packages/graphiql/cypress/e2e/a11y.cy.ts b/packages/graphiql/cypress/e2e/a11y.cy.ts
new file mode 100644
index 00000000000..9474b9c169f
--- /dev/null
+++ b/packages/graphiql/cypress/e2e/a11y.cy.ts
@@ -0,0 +1,104 @@
+/// <reference types="cypress" />
+/// <reference types="cypress-axe" />
+
+import baseline from '../.a11y-baseline.json';
+
+type ViolationSummary = {
+  id: string;
+  impact: string | null;
+  nodeCount: number;
+};
+
+type Baseline = Record<string, ViolationSummary[]>;
+
+const UPDATE_BASELINE = Boolean(Cypress.env('A11Y_UPDATE_BASELINE'));
+
+const RULESET = {
+  runOnly: {
+    type: 'tag' as const,
+    values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
+  },
+};
+
+const accumulated: Baseline = {};
+
+function toSummary(v: {
+  id: string;
+  impact?: string | null;
+  nodes: unknown[];
+}): ViolationSummary {
+  return { id: v.id, impact: v.impact ?? null, nodeCount: v.nodes.length };
+}
+
+function checkOrCapture(checkpoint: string) {
+  cy.checkA11y(
+    undefined,
+    RULESET,
+    violations => {
+      if (UPDATE_BASELINE) {
+        accumulated[checkpoint] = violations.map(toSummary);
+        // Task runs in Node; path is relative to the package root.
+        // cypress.config.ts wires up the writeBaseline task.
+        cy.task('writeBaseline', {
+          filePath: 'cypress/.a11y-baseline.json',
+          data: { ...(baseline as Baseline), ...accumulated },
+        });
+      } else {
+        const baselineEntries: ViolationSummary[] =
+          (baseline as Baseline)[checkpoint] ?? [];
+        // Compare by violation id only — node counts drift between local
+        // (Electron on macOS) and CI (headless Chromium on Linux) for the
+        // same underlying issues, so they're not a reliable key.
+        const baselineKeys = new Set(baselineEntries.map(v => v.id));
+        const newViolations = violations.filter(v => !baselineKeys.has(v.id));
+        if (newViolations.length > 0) {
+          const summary = newViolations
+            .map(v => `${v.id} (${v.impact}): ${v.help}`)
+            .join('\n');
+          throw new Error(
+            `New a11y violations at "${checkpoint}":\n${summary}`,
+          );
+        }
+      }
+    },
+    // Don't let cypress-axe auto-throw — the callback above is the only
+    // source of failures (compare-against-baseline in normal mode; capture
+    // and write in update mode).
+    true,
+  );
+}
+
+describe('a11y baseline', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.injectAxe();
+  });
+
+  it('initial render has no new violations', () => {
+    checkOrCapture('initial');
+  });
+
+  it('after running a query has no new violations', () => {
+    cy.clickExecuteQuery();
+    // Wait for the response panel to populate before scanning
+    cy.get('section.result-window').should('not.have.text', '');
+    cy.injectAxe();
+    checkOrCapture('post-run');
+  });
+
+  it('with docs panel open has no new violations', () => {
+    // First sidebar button is the docs explorer toggle (confirmed in docs.cy.ts)
+    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-doc-explorer').should('be.visible');
+    cy.injectAxe();
+    checkOrCapture('docs-open');
+  });
+
+  it('with history panel open has no new violations', () => {
+    // history.cy.ts uses this exact selector
+    cy.get('button[aria-label="Show History"]').click();
+    cy.get('.graphiql-history').should('be.visible');
+    cy.injectAxe();
+    checkOrCapture('history-open');
+  });
+});
diff --git a/packages/graphiql/cypress/support/e2e.ts b/packages/graphiql/cypress/support/e2e.ts
index f9e2ea7fdcb..5727497621d 100644
--- a/packages/graphiql/cypress/support/e2e.ts
+++ b/packages/graphiql/cypress/support/e2e.ts
@@ -15,3 +15,4 @@
 /// <reference types="cypress" />
 
 import './commands';
+import 'cypress-axe';
diff --git a/packages/graphiql/cypress/tsconfig.json b/packages/graphiql/cypress/tsconfig.json
index 48cb1263dad..d5fb01f9ac7 100644
--- a/packages/graphiql/cypress/tsconfig.json
+++ b/packages/graphiql/cypress/tsconfig.json
@@ -4,7 +4,9 @@
     "lib": ["es2021", "dom"],
     "types": ["cypress", "node"],
     "strictNullChecks": true,
-    "strict": true
+    "strict": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true
   },
   "include": ["**/*.ts"]
 }
diff --git a/packages/graphiql/package.json b/packages/graphiql/package.json
index 969d3a195bb..3482344f1a0 100644
--- a/packages/graphiql/package.json
+++ b/packages/graphiql/package.json
@@ -46,6 +46,7 @@
     "cypress-open": "cypress open --browser electron",
     "dev": "concurrently 'cross-env PORT=8080 node test/e2e-server' vite",
     "e2e": "yarn e2e-server 'cypress run'",
+    "test:a11y:update": "CYPRESS_A11Y_UPDATE_BASELINE=1 yarn e2e-server 'cypress run --spec cypress/e2e/a11y.cy.ts'",
     "e2e-server": "start-server-and-test 'cross-env PORT=8080 node test/e2e-server' 'http-get://localhost:8080/graphql?query={test { id }}'",
     "test": "vitest run"
   },
@@ -67,9 +68,11 @@
     "@testing-library/react": "^16.3.0",
     "@vitejs/plugin-react": "^4.4.1",
     "@vitest/web-worker": "^4.1.6",
+    "axe-core": "^4",
     "babel-plugin-react-compiler": "19.1.0-rc.1",
     "cross-env": "^7.0.2",
     "cypress": "^13.13.2",
+    "cypress-axe": "^1",
     "graphql": "^16.11.0",
     "lightningcss": "^1.29.3",
     "react": "^19.1.0",
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index e2737fd1f2b..a06ed5fcbbd 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -189,6 +189,7 @@ roadmap
 roboto
 rodionov
 rohit
+ruleset
 runmode
 runtimes
 saihaj
@@ -242,6 +243,7 @@ vitejs
 vitest
 vizag
 vsix
+wcag
 webp
 websockets
 wgutils
diff --git a/yarn.lock b/yarn.lock
index 587b4c5b5d3..3491f7110a3 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2379,25 +2379,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@emnapi/core@npm:1.9.2":
-  version: 1.9.2
-  resolution: "@emnapi/core@npm:1.9.2"
-  dependencies:
-    "@emnapi/wasi-threads": "npm:1.2.1"
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/5500393f953951bad0768fafaa9191f2d938956b20c6d6a79e5ab696a613a25ce6ad23422bc18e86e6ce8deb147619d8d0d7d413a69f84adc01a6633cc353cd9
-  languageName: node
-  linkType: hard
-
-"@emnapi/runtime@npm:1.9.2":
-  version: 1.9.2
-  resolution: "@emnapi/runtime@npm:1.9.2"
-  dependencies:
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/61c3a59e0c36784558b8d58eb02bd04815aa5fb0dbfbaf84d1b3050a78aa0cc63ea129ae806bd1e48062bfeb7fc36eb0e5431740d62f64ea51bdf426404b8caa
-  languageName: node
-  linkType: hard
-
 "@emnapi/runtime@npm:^1.7.0":
   version: 1.10.0
   resolution: "@emnapi/runtime@npm:1.10.0"
@@ -2407,15 +2388,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@emnapi/wasi-threads@npm:1.2.1":
-  version: 1.2.1
-  resolution: "@emnapi/wasi-threads@npm:1.2.1"
-  dependencies:
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/32fcfa81ab396533b2ec1f4082b1ff779a05d9c836bbbd3f4398405b0e6814c0d9503b7993130e37bc6941dbc1ded49f55e9700ae9ca4e803bab2b5bc5deb331
-  languageName: node
-  linkType: hard
-
 "@envelop/core@npm:^5.4.0":
   version: 5.5.1
   resolution: "@envelop/core@npm:5.5.1"
@@ -4304,18 +4276,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@napi-rs/wasm-runtime@npm:^1.1.1, @napi-rs/wasm-runtime@npm:^1.1.4":
-  version: 1.1.4
-  resolution: "@napi-rs/wasm-runtime@npm:1.1.4"
-  dependencies:
-    "@tybys/wasm-util": "npm:^0.10.1"
-  peerDependencies:
-    "@emnapi/core": ^1.7.1
-    "@emnapi/runtime": ^1.7.1
-  checksum: 10c0/2e88e1955258949ccf2d18c79975821ad38071b465ef126a5e14110977b97868867b016c1ad046e963cccc42c0bd9db6c8ff5fd1ebb61b87bb3487f339041658
-  languageName: node
-  linkType: hard
-
 "@next/env@npm:15.5.15":
   version: 15.5.15
   resolution: "@next/env@npm:15.5.15"
@@ -4473,299 +4433,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@oxc-parser/binding-android-arm-eabi@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-android-arm-eabi@npm:0.127.0"
-  conditions: os=android & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-android-arm64@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-android-arm64@npm:0.127.0"
-  conditions: os=android & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-darwin-arm64@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-darwin-arm64@npm:0.127.0"
-  conditions: os=darwin & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-darwin-x64@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-darwin-x64@npm:0.127.0"
-  conditions: os=darwin & cpu=x64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-freebsd-x64@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-freebsd-x64@npm:0.127.0"
-  conditions: os=freebsd & cpu=x64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-arm-gnueabihf@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-arm-gnueabihf@npm:0.127.0"
-  conditions: os=linux & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-arm-musleabihf@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-arm-musleabihf@npm:0.127.0"
-  conditions: os=linux & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-arm64-gnu@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-arm64-gnu@npm:0.127.0"
-  conditions: os=linux & cpu=arm64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-arm64-musl@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-arm64-musl@npm:0.127.0"
-  conditions: os=linux & cpu=arm64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-ppc64-gnu@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-ppc64-gnu@npm:0.127.0"
-  conditions: os=linux & cpu=ppc64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-riscv64-gnu@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-riscv64-gnu@npm:0.127.0"
-  conditions: os=linux & cpu=riscv64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-riscv64-musl@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-riscv64-musl@npm:0.127.0"
-  conditions: os=linux & cpu=riscv64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-s390x-gnu@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-s390x-gnu@npm:0.127.0"
-  conditions: os=linux & cpu=s390x & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-x64-gnu@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-x64-gnu@npm:0.127.0"
-  conditions: os=linux & cpu=x64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-linux-x64-musl@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-linux-x64-musl@npm:0.127.0"
-  conditions: os=linux & cpu=x64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-openharmony-arm64@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-openharmony-arm64@npm:0.127.0"
-  conditions: os=openharmony & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-wasm32-wasi@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-wasm32-wasi@npm:0.127.0"
-  dependencies:
-    "@emnapi/core": "npm:1.9.2"
-    "@emnapi/runtime": "npm:1.9.2"
-    "@napi-rs/wasm-runtime": "npm:^1.1.4"
-  conditions: cpu=wasm32
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-win32-arm64-msvc@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-win32-arm64-msvc@npm:0.127.0"
-  conditions: os=win32 & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-win32-ia32-msvc@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-win32-ia32-msvc@npm:0.127.0"
-  conditions: os=win32 & cpu=ia32
-  languageName: node
-  linkType: hard
-
-"@oxc-parser/binding-win32-x64-msvc@npm:0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-parser/binding-win32-x64-msvc@npm:0.127.0"
-  conditions: os=win32 & cpu=x64
-  languageName: node
-  linkType: hard
-
-"@oxc-project/types@npm:^0.127.0":
-  version: 0.127.0
-  resolution: "@oxc-project/types@npm:0.127.0"
-  checksum: 10c0/52c0947ac64a9ca119fe971f947e784a35ecd14a072fa3f542a58a5f6c42010b53f2bf92731e39b9899b83c990a9517bbd29d1e5a5b7b489e52616685c6a9278
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-android-arm-eabi@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-android-arm-eabi@npm:11.19.1"
-  conditions: os=android & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-android-arm64@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-android-arm64@npm:11.19.1"
-  conditions: os=android & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-darwin-arm64@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-darwin-arm64@npm:11.19.1"
-  conditions: os=darwin & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-darwin-x64@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-darwin-x64@npm:11.19.1"
-  conditions: os=darwin & cpu=x64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-freebsd-x64@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-freebsd-x64@npm:11.19.1"
-  conditions: os=freebsd & cpu=x64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-arm-gnueabihf@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-arm-gnueabihf@npm:11.19.1"
-  conditions: os=linux & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-arm-musleabihf@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-arm-musleabihf@npm:11.19.1"
-  conditions: os=linux & cpu=arm
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-arm64-gnu@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-arm64-gnu@npm:11.19.1"
-  conditions: os=linux & cpu=arm64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-arm64-musl@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-arm64-musl@npm:11.19.1"
-  conditions: os=linux & cpu=arm64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-ppc64-gnu@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-ppc64-gnu@npm:11.19.1"
-  conditions: os=linux & cpu=ppc64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-riscv64-gnu@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-riscv64-gnu@npm:11.19.1"
-  conditions: os=linux & cpu=riscv64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-riscv64-musl@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-riscv64-musl@npm:11.19.1"
-  conditions: os=linux & cpu=riscv64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-s390x-gnu@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-s390x-gnu@npm:11.19.1"
-  conditions: os=linux & cpu=s390x & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-x64-gnu@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-x64-gnu@npm:11.19.1"
-  conditions: os=linux & cpu=x64 & libc=glibc
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-linux-x64-musl@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-linux-x64-musl@npm:11.19.1"
-  conditions: os=linux & cpu=x64 & libc=musl
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-openharmony-arm64@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-openharmony-arm64@npm:11.19.1"
-  conditions: os=openharmony & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-wasm32-wasi@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-wasm32-wasi@npm:11.19.1"
-  dependencies:
-    "@napi-rs/wasm-runtime": "npm:^1.1.1"
-  conditions: cpu=wasm32
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-win32-arm64-msvc@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-win32-arm64-msvc@npm:11.19.1"
-  conditions: os=win32 & cpu=arm64
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-win32-ia32-msvc@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-win32-ia32-msvc@npm:11.19.1"
-  conditions: os=win32 & cpu=ia32
-  languageName: node
-  linkType: hard
-
-"@oxc-resolver/binding-win32-x64-msvc@npm:11.19.1":
-  version: 11.19.1
-  resolution: "@oxc-resolver/binding-win32-x64-msvc@npm:11.19.1"
-  conditions: os=win32 & cpu=x64
-  languageName: node
-  linkType: hard
-
 "@oxfmt/binding-android-arm-eabi@npm:0.45.0":
   version: 0.45.0
   resolution: "@oxfmt/binding-android-arm-eabi@npm:0.45.0"
@@ -6392,28 +6059,28 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/builder-vite@npm:10.4.0":
-  version: 10.4.0
-  resolution: "@storybook/builder-vite@npm:10.4.0"
+"@storybook/builder-vite@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/builder-vite@npm:10.3.6"
   dependencies:
-    "@storybook/csf-plugin": "npm:10.4.0"
+    "@storybook/csf-plugin": "npm:10.3.6"
     ts-dedent: "npm:^2.0.0"
   peerDependencies:
-    storybook: ^10.4.0
+    storybook: ^10.3.6
     vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
-  checksum: 10c0/416240f36b7e93520a6d1168470614fce615062c3c39ea1ad9fe1defffc4f50716b2923210d4e89fa68c1162d89a6f646ef29a08759ed2430ccbf1c0c89453b6
+  checksum: 10c0/f7e5c57362ba8df8dac4f71dc86d4117cd1edfaf2f61a3ecb0d6bece6b37357f1dc0bf135fd27b5552055b47e0fce5ffba67ffeb2fdedbc75fc986997062bf28
   languageName: node
   linkType: hard
 
-"@storybook/csf-plugin@npm:10.4.0":
-  version: 10.4.0
-  resolution: "@storybook/csf-plugin@npm:10.4.0"
+"@storybook/csf-plugin@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/csf-plugin@npm:10.3.6"
   dependencies:
     unplugin: "npm:^2.3.5"
   peerDependencies:
     esbuild: "*"
     rollup: "*"
-    storybook: ^10.4.0
+    storybook: ^10.3.6
     vite: "*"
     webpack: "*"
   peerDependenciesMeta:
@@ -6425,7 +6092,7 @@ __metadata:
       optional: true
     webpack:
       optional: true
-  checksum: 10c0/9c968636b14beb9b740b42c3e0f0b81ef2662344bb2328e1149b62e71d3e1e45d82bb08788b6a3fe7755c2884d0b5cf8e033937a07659047764dcfeb91cce80b
+  checksum: 10c0/593fc6b9b6073c9dacd26f595ccb58f1ac28f3ab3cf63bf3d8d6913285765eb9c4fdb3e1c54356804ec8eccdde24f14cfa7af3e528731eb6d7e52266d81c4213
   languageName: node
   linkType: hard
 
@@ -6436,7 +6103,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/icons@npm:^2.0.2":
+"@storybook/icons@npm:^2.0.1":
   version: 2.0.2
   resolution: "@storybook/icons@npm:2.0.2"
   peerDependencies:
@@ -6446,32 +6113,25 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/react-dom-shim@npm:10.4.0":
-  version: 10.4.0
-  resolution: "@storybook/react-dom-shim@npm:10.4.0"
+"@storybook/react-dom-shim@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/react-dom-shim@npm:10.3.6"
   peerDependencies:
-    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    "@types/react-dom": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.4.0
-  peerDependenciesMeta:
-    "@types/react":
-      optional: true
-    "@types/react-dom":
-      optional: true
-  checksum: 10c0/d2a07900dd7d35403abb29f23f0f58a53e552003c713a004b465bfc8a781399e3a6062682fe950b79faf5b45bb1955139abe69b6d9f4c3478688b30ebd669274
+    storybook: ^10.3.6
+  checksum: 10c0/60183fc05b0410ca174f215d3271ffbccdc2680bd0704f58dc931cf60e72f497a9f22c00afa868398ad693c7ec633ef619541d4b0611fc2a577fb09609fcc3c7
   languageName: node
   linkType: hard
 
 "@storybook/react-vite@npm:^10.3.6":
-  version: 10.4.0
-  resolution: "@storybook/react-vite@npm:10.4.0"
+  version: 10.3.6
+  resolution: "@storybook/react-vite@npm:10.3.6"
   dependencies:
     "@joshwooding/vite-plugin-react-docgen-typescript": "npm:^0.7.0"
     "@rollup/pluginutils": "npm:^5.0.2"
-    "@storybook/builder-vite": "npm:10.4.0"
-    "@storybook/react": "npm:10.4.0"
+    "@storybook/builder-vite": "npm:10.3.6"
+    "@storybook/react": "npm:10.3.6"
     empathic: "npm:^2.0.0"
     magic-string: "npm:^0.30.0"
     react-docgen: "npm:^8.0.0"
@@ -6480,35 +6140,29 @@ __metadata:
   peerDependencies:
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.4.0
+    storybook: ^10.3.6
     vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
-  checksum: 10c0/3674c84a59ab75df75bc56fcce9e50464bea05c0d02f6ff6733b734b57d6629b501844a4a9491f01df945eec8c65dd14d9d97552d45aaff49a9782453ee476cf
+  checksum: 10c0/3b939caf05985f0c6d5049c49b71fd8c7abac1f94f1559cfa135a755f3d94c0ef29bdd8d7f7f68c4676ea66852ed4b43d2e33d18434aa1c72f4aebca928b3e13
   languageName: node
   linkType: hard
 
-"@storybook/react@npm:10.4.0":
-  version: 10.4.0
-  resolution: "@storybook/react@npm:10.4.0"
+"@storybook/react@npm:10.3.6":
+  version: 10.3.6
+  resolution: "@storybook/react@npm:10.3.6"
   dependencies:
     "@storybook/global": "npm:^5.0.0"
-    "@storybook/react-dom-shim": "npm:10.4.0"
+    "@storybook/react-dom-shim": "npm:10.3.6"
     react-docgen: "npm:^8.0.2"
     react-docgen-typescript: "npm:^2.2.2"
   peerDependencies:
-    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    "@types/react-dom": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.4.0
+    storybook: ^10.3.6
     typescript: ">= 4.9.x"
   peerDependenciesMeta:
-    "@types/react":
-      optional: true
-    "@types/react-dom":
-      optional: true
     typescript:
       optional: true
-  checksum: 10c0/b23acb83cb5eccd0b37eb2a73158ed444b702f7e484277e6e65ac05d18dff2c3b1dd45c00941a86e7acd4ba3edfe14f79448c9316915426dbce2752ecceeaa5e
+  checksum: 10c0/3d3af66105cdca98c537b4bcc3e92f87e3b56d154b24e9b167300e9d5de8a7ba6a5ef3c22203ccb6f4c2f0602a5546273b2b49728aa383ba0f98e66a286647a8
   languageName: node
   linkType: hard
 
@@ -6713,22 +6367,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@testing-library/jest-dom@npm:^6.6.3":
-  version: 6.6.3
-  resolution: "@testing-library/jest-dom@npm:6.6.3"
-  dependencies:
-    "@adobe/css-tools": "npm:^4.4.0"
-    aria-query: "npm:^5.0.0"
-    chalk: "npm:^3.0.0"
-    css.escape: "npm:^1.5.1"
-    dom-accessibility-api: "npm:^0.6.3"
-    lodash: "npm:^4.17.21"
-    redent: "npm:^3.0.0"
-  checksum: 10c0/5566b6c0b7b0709bc244aec3aa3dc9e5f4663e8fb2b99d8cd456fc07279e59db6076cbf798f9d3099a98fca7ef4cd50e4e1f4c4dec5a60a8fad8d24a638a5bf6
-  languageName: node
-  linkType: hard
-
-"@testing-library/jest-dom@npm:^6.9.1":
+"@testing-library/jest-dom@npm:^6.6.3, @testing-library/jest-dom@npm:^6.9.1":
   version: 6.9.1
   resolution: "@testing-library/jest-dom@npm:6.9.1"
   dependencies:
@@ -6771,15 +6410,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@tybys/wasm-util@npm:^0.10.1":
-  version: 0.10.2
-  resolution: "@tybys/wasm-util@npm:0.10.2"
-  dependencies:
-    tslib: "npm:^2.4.0"
-  checksum: 10c0/26165bcd1fd7269f42d7fbe3de318f854a8968de8397e89fc9a423bb3e2da35a52150f382e6323b3367595beb16d9800a6f35971a5599daf76da1742ec3afc25
-  languageName: node
-  linkType: hard
-
 "@types/argparse@npm:1.0.38":
   version: 1.0.38
   resolution: "@types/argparse@npm:1.0.38"
@@ -6826,16 +6456,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/babel__traverse@npm:*":
-  version: 7.20.1
-  resolution: "@types/babel__traverse@npm:7.20.1"
-  dependencies:
-    "@babel/types": "npm:^7.20.7"
-  checksum: 10c0/5a6a3a26be090573309527184a31f1b82ef55f3d73d811c15f181d323e471305f2390651a04d49d4cd4ca41bbeabb53c9f7862a8e09eab5a0f8910a6aec6e867
-  languageName: node
-  linkType: hard
-
-"@types/babel__traverse@npm:^7.20.7":
+"@types/babel__traverse@npm:*, @types/babel__traverse@npm:^7.20.7":
   version: 7.28.0
   resolution: "@types/babel__traverse@npm:7.28.0"
   dependencies:
@@ -9008,6 +8629,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"axe-core@npm:^4":
+  version: 4.11.4
+  resolution: "axe-core@npm:4.11.4"
+  checksum: 10c0/c4aa83fc3eac5f7a0d0cb1a28f9d073acf0c06ce8daacc38608faa278c57ce084c028c850746b98817ae4c101c30c1a32e95ea34748c4b4c7419b9b81221ef84
+  languageName: node
+  linkType: hard
+
 "axios@npm:^0.21.1":
   version: 0.21.4
   resolution: "axios@npm:0.21.4"
@@ -9656,16 +9284,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chalk@npm:^3.0.0":
-  version: 3.0.0
-  resolution: "chalk@npm:3.0.0"
-  dependencies:
-    ansi-styles: "npm:^4.1.0"
-    supports-color: "npm:^7.1.0"
-  checksum: 10c0/ee650b0a065b3d7a6fda258e75d3a86fc8e4effa55871da730a9e42ccb035bf5fd203525e5a1ef45ec2582ecc4f65b47eb11357c526b84dd29a14fb162c414d2
-  languageName: node
-  linkType: hard
-
 "chalk@npm:^4.0.2, chalk@npm:^4.1.0, chalk@npm:^4.1.2":
   version: 4.1.2
   resolution: "chalk@npm:4.1.2"
@@ -9684,9 +9302,9 @@ __metadata:
   linkType: hard
 
 "check-error@npm:^2.1.1":
-  version: 2.1.3
-  resolution: "check-error@npm:2.1.3"
-  checksum: 10c0/878e99038fb6476316b74668cd6a498c7e66df3efe48158fa40db80a06ba4258742ac3ee2229c4a2a98c5e73f5dff84eb3e50ceb6b65bbd8f831eafc8338607d
+  version: 2.1.1
+  resolution: "check-error@npm:2.1.1"
+  checksum: 10c0/979f13eccab306cf1785fa10941a590b4e7ea9916ea2a4f8c87f0316fc3eab07eabefb6e587424ef0f88cbcd3805791f172ea739863ca3d7ce2afc54641c7f0e
   languageName: node
   linkType: hard
 
@@ -10741,6 +10359,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cypress-axe@npm:^1":
+  version: 1.7.0
+  resolution: "cypress-axe@npm:1.7.0"
+  peerDependencies:
+    axe-core: ^3 || ^4
+    cypress: ^10 || ^11 || ^12 || ^13 || ^14 || ^15
+  checksum: 10c0/93d53eaaf0abb2eed61b0ecbf890bbb2b063db0941be70fa945697f09f5d33d0747fe518778eb25b32326bdea08cd8f4a00b8e4633aea4fe8a8d00b55fb02b15
+  languageName: node
+  linkType: hard
+
 "cypress@npm:^13.13.2":
   version: 13.13.2
   resolution: "cypress@npm:13.13.2"
@@ -13876,9 +13504,11 @@ __metadata:
     "@testing-library/react": "npm:^16.3.0"
     "@vitejs/plugin-react": "npm:^4.4.1"
     "@vitest/web-worker": "npm:^4.1.6"
+    axe-core: "npm:^4"
     babel-plugin-react-compiler: "npm:19.1.0-rc.1"
     cross-env: "npm:^7.0.2"
     cypress: "npm:^13.13.2"
+    cypress-axe: "npm:^1"
     graphql: "npm:^16.11.0"
     lightningcss: "npm:^1.29.3"
     react: "npm:^19.1.0"
@@ -16895,14 +16525,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2":
-  version: 7.1.2
-  resolution: "minipass@npm:7.1.2"
-  checksum: 10c0/b0fd20bb9fb56e5fa9a8bfac539e8915ae07430a619e4b86ff71f5fc757ef3924b23b2c4230393af1eda647ed3d75739e4e0acb250a6b1eb277cf7f8fe449557
-  languageName: node
-  linkType: hard
-
-"minipass@npm:^7.1.3":
+"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2, minipass@npm:^7.1.3":
   version: 7.1.3
   resolution: "minipass@npm:7.1.3"
   checksum: 10c0/539da88daca16533211ea5a9ee98dc62ff5742f531f54640dd34429e621955e91cc280a91a776026264b7f9f6735947629f920944e9c1558369e8bf22eb33fbb
@@ -17659,19 +17282,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"open@npm:^10.0.3":
-  version: 10.1.2
-  resolution: "open@npm:10.1.2"
-  dependencies:
-    default-browser: "npm:^5.2.1"
-    define-lazy-prop: "npm:^3.0.0"
-    is-inside-container: "npm:^1.0.0"
-    is-wsl: "npm:^3.1.0"
-  checksum: 10c0/1bee796f06e549ce764f693272100323fbc04da8fa3c5b0402d6c2d11b3d76fa0aac0be7535e710015ff035326638e3b9a563f3b0e7ac3266473ed5663caae6d
-  languageName: node
-  linkType: hard
-
-"open@npm:^10.2.0":
+"open@npm:^10.0.3, open@npm:^10.2.0":
   version: 10.2.0
   resolution: "open@npm:10.2.0"
   dependencies:
@@ -17776,145 +17387,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"oxc-parser@npm:^0.127.0":
-  version: 0.127.0
-  resolution: "oxc-parser@npm:0.127.0"
-  dependencies:
-    "@oxc-parser/binding-android-arm-eabi": "npm:0.127.0"
-    "@oxc-parser/binding-android-arm64": "npm:0.127.0"
-    "@oxc-parser/binding-darwin-arm64": "npm:0.127.0"
-    "@oxc-parser/binding-darwin-x64": "npm:0.127.0"
-    "@oxc-parser/binding-freebsd-x64": "npm:0.127.0"
-    "@oxc-parser/binding-linux-arm-gnueabihf": "npm:0.127.0"
-    "@oxc-parser/binding-linux-arm-musleabihf": "npm:0.127.0"
-    "@oxc-parser/binding-linux-arm64-gnu": "npm:0.127.0"
-    "@oxc-parser/binding-linux-arm64-musl": "npm:0.127.0"
-    "@oxc-parser/binding-linux-ppc64-gnu": "npm:0.127.0"
-    "@oxc-parser/binding-linux-riscv64-gnu": "npm:0.127.0"
-    "@oxc-parser/binding-linux-riscv64-musl": "npm:0.127.0"
-    "@oxc-parser/binding-linux-s390x-gnu": "npm:0.127.0"
-    "@oxc-parser/binding-linux-x64-gnu": "npm:0.127.0"
-    "@oxc-parser/binding-linux-x64-musl": "npm:0.127.0"
-    "@oxc-parser/binding-openharmony-arm64": "npm:0.127.0"
-    "@oxc-parser/binding-wasm32-wasi": "npm:0.127.0"
-    "@oxc-parser/binding-win32-arm64-msvc": "npm:0.127.0"
-    "@oxc-parser/binding-win32-ia32-msvc": "npm:0.127.0"
-    "@oxc-parser/binding-win32-x64-msvc": "npm:0.127.0"
-    "@oxc-project/types": "npm:^0.127.0"
-  dependenciesMeta:
-    "@oxc-parser/binding-android-arm-eabi":
-      optional: true
-    "@oxc-parser/binding-android-arm64":
-      optional: true
-    "@oxc-parser/binding-darwin-arm64":
-      optional: true
-    "@oxc-parser/binding-darwin-x64":
-      optional: true
-    "@oxc-parser/binding-freebsd-x64":
-      optional: true
-    "@oxc-parser/binding-linux-arm-gnueabihf":
-      optional: true
-    "@oxc-parser/binding-linux-arm-musleabihf":
-      optional: true
-    "@oxc-parser/binding-linux-arm64-gnu":
-      optional: true
-    "@oxc-parser/binding-linux-arm64-musl":
-      optional: true
-    "@oxc-parser/binding-linux-ppc64-gnu":
-      optional: true
-    "@oxc-parser/binding-linux-riscv64-gnu":
-      optional: true
-    "@oxc-parser/binding-linux-riscv64-musl":
-      optional: true
-    "@oxc-parser/binding-linux-s390x-gnu":
-      optional: true
-    "@oxc-parser/binding-linux-x64-gnu":
-      optional: true
-    "@oxc-parser/binding-linux-x64-musl":
-      optional: true
-    "@oxc-parser/binding-openharmony-arm64":
-      optional: true
-    "@oxc-parser/binding-wasm32-wasi":
-      optional: true
-    "@oxc-parser/binding-win32-arm64-msvc":
-      optional: true
-    "@oxc-parser/binding-win32-ia32-msvc":
-      optional: true
-    "@oxc-parser/binding-win32-x64-msvc":
-      optional: true
-  checksum: 10c0/9d109fb3a79c0862a36434cc01c8c0e8f6cf5f1efe9369e02d2183fd518479b10262cf092da2e7f8328befae446afa05ccf742ce12f8346d81429c8f2cdf1651
-  languageName: node
-  linkType: hard
-
-"oxc-resolver@npm:^11.19.1":
-  version: 11.19.1
-  resolution: "oxc-resolver@npm:11.19.1"
-  dependencies:
-    "@oxc-resolver/binding-android-arm-eabi": "npm:11.19.1"
-    "@oxc-resolver/binding-android-arm64": "npm:11.19.1"
-    "@oxc-resolver/binding-darwin-arm64": "npm:11.19.1"
-    "@oxc-resolver/binding-darwin-x64": "npm:11.19.1"
-    "@oxc-resolver/binding-freebsd-x64": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-arm-gnueabihf": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-arm-musleabihf": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-arm64-gnu": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-arm64-musl": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-ppc64-gnu": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-riscv64-gnu": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-riscv64-musl": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-s390x-gnu": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-x64-gnu": "npm:11.19.1"
-    "@oxc-resolver/binding-linux-x64-musl": "npm:11.19.1"
-    "@oxc-resolver/binding-openharmony-arm64": "npm:11.19.1"
-    "@oxc-resolver/binding-wasm32-wasi": "npm:11.19.1"
-    "@oxc-resolver/binding-win32-arm64-msvc": "npm:11.19.1"
-    "@oxc-resolver/binding-win32-ia32-msvc": "npm:11.19.1"
-    "@oxc-resolver/binding-win32-x64-msvc": "npm:11.19.1"
-  dependenciesMeta:
-    "@oxc-resolver/binding-android-arm-eabi":
-      optional: true
-    "@oxc-resolver/binding-android-arm64":
-      optional: true
-    "@oxc-resolver/binding-darwin-arm64":
-      optional: true
-    "@oxc-resolver/binding-darwin-x64":
-      optional: true
-    "@oxc-resolver/binding-freebsd-x64":
-      optional: true
-    "@oxc-resolver/binding-linux-arm-gnueabihf":
-      optional: true
-    "@oxc-resolver/binding-linux-arm-musleabihf":
-      optional: true
-    "@oxc-resolver/binding-linux-arm64-gnu":
-      optional: true
-    "@oxc-resolver/binding-linux-arm64-musl":
-      optional: true
-    "@oxc-resolver/binding-linux-ppc64-gnu":
-      optional: true
-    "@oxc-resolver/binding-linux-riscv64-gnu":
-      optional: true
-    "@oxc-resolver/binding-linux-riscv64-musl":
-      optional: true
-    "@oxc-resolver/binding-linux-s390x-gnu":
-      optional: true
-    "@oxc-resolver/binding-linux-x64-gnu":
-      optional: true
-    "@oxc-resolver/binding-linux-x64-musl":
-      optional: true
-    "@oxc-resolver/binding-openharmony-arm64":
-      optional: true
-    "@oxc-resolver/binding-wasm32-wasi":
-      optional: true
-    "@oxc-resolver/binding-win32-arm64-msvc":
-      optional: true
-    "@oxc-resolver/binding-win32-ia32-msvc":
-      optional: true
-    "@oxc-resolver/binding-win32-x64-msvc":
-      optional: true
-  checksum: 10c0/8ac4eaffa9c0bcbb9f4f4a2b43786457ec5a68684d8776cb78b5a15ce3d1a79d3e67262aa3c635f98a0c1cd6cd56a31fcb05bffb9a286100056e4ab06b928833
-  languageName: node
-  linkType: hard
-
 "oxfmt@npm:^0.45.0":
   version: 0.45.0
   resolution: "oxfmt@npm:0.45.0"
@@ -18513,9 +17985,9 @@ __metadata:
   linkType: hard
 
 "pathval@npm:^2.0.0":
-  version: 2.0.1
-  resolution: "pathval@npm:2.0.1"
-  checksum: 10c0/460f4709479fbf2c45903a65655fc8f0a5f6d808f989173aeef5fdea4ff4f303dc13f7870303999add60ec49d4c14733895c0a869392e9866f1091fa64fd7581
+  version: 2.0.0
+  resolution: "pathval@npm:2.0.0"
+  checksum: 10c0/602e4ee347fba8a599115af2ccd8179836a63c925c23e04bd056d0674a64b39e3a081b643cc7bc0b84390517df2d800a46fcc5598d42c155fe4977095c2f77c5
   languageName: node
   linkType: hard
 
@@ -20896,11 +20368,11 @@ __metadata:
   linkType: hard
 
 "storybook@npm:^10.3.6":
-  version: 10.4.0
-  resolution: "storybook@npm:10.4.0"
+  version: 10.3.6
+  resolution: "storybook@npm:10.3.6"
   dependencies:
     "@storybook/global": "npm:^5.0.0"
-    "@storybook/icons": "npm:^2.0.2"
+    "@storybook/icons": "npm:^2.0.1"
     "@testing-library/jest-dom": "npm:^6.9.1"
     "@testing-library/user-event": "npm:^14.6.1"
     "@vitest/expect": "npm:3.2.4"
@@ -20908,26 +20380,21 @@ __metadata:
     "@webcontainer/env": "npm:^1.1.1"
     esbuild: "npm:^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0"
     open: "npm:^10.2.0"
-    oxc-parser: "npm:^0.127.0"
-    oxc-resolver: "npm:^11.19.1"
     recast: "npm:^0.23.5"
     semver: "npm:^7.7.3"
     use-sync-external-store: "npm:^1.5.0"
     ws: "npm:^8.18.0"
   peerDependencies:
-    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     prettier: ^2 || ^3
     vite-plus: ^0.1.15
   peerDependenciesMeta:
-    "@types/react":
-      optional: true
     prettier:
       optional: true
     vite-plus:
       optional: true
   bin:
     storybook: ./dist/bin/dispatcher.js
-  checksum: 10c0/f6e493819b68dbf4a182cd31d5717db08481a25cfc8c4ab6139fbb70e039a9d4e6d54ff1f8280d3b6052a06ef32242d3753bd9cbbdf91392f4c65a92acf8cff6
+  checksum: 10c0/ee6702667459ba2d49269ddd63a7281f17816fcdd4bacd338ed47a4a8e7ad65760c90d99f6b2dfdfd0a564bcfcab3c1ea05b50bf3aafc6b5b19a039a5da77870
   languageName: node
   linkType: hard
 

From e0ebc5b413c57e66f26903e91c3c864f14e7ec43 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 14 May 2026 15:21:08 -0700
Subject: [PATCH 07/38] v6: Wire axe into Storybook stories via
 `@storybook/addon-vitest` (#4262)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Component-level a11y for v6. `@storybook/addon-a11y` surfaces axe
results next to each story while you're working on it;
`@storybook/addon-vitest` folds those same checks into the existing
Vitest suite so they run as part of `yarn test` in CI.

The model is per-story `parameters.a11y.test`:

- `'error'` (default) — axe violations fail the test
- `'todo'` — warn only, for stories with known issues we plan to fix
- `'off'` — skip a11y for the story

`vitest.config.mts` is split into two projects:

- `unit` — existing jsdom suite, unchanged behavior
- `storybook` — Vitest browser mode (Playwright Chromium), picks up
`.stories.*` files

The PR CI workflow gets one new step: `yarn playwright install
--with-deps chromium` ahead of `yarn test`.

## Run locally

```
yarn workspace @graphiql/react test                       # both projects
yarn workspace @graphiql/react vitest run --project=unit  # unit only
yarn workspace @graphiql/react vitest run --project=storybook
```

The Storybook a11y panel surfaces the same axe results live during `yarn
workspace @graphiql/react storybook`.

Refs: graphql/graphiql#4219
---
 .github/workflows/pr.yml                      |   1 +
 packages/graphiql-react/.storybook/main.ts    |   2 +-
 .../graphiql-react/.storybook/preview.tsx     |   1 +
 packages/graphiql-react/package.json          |   4 +
 packages/graphiql-react/vitest.config.mts     |  44 +-
 yarn.lock                                     | 846 ++++++++++++++++--
 6 files changed, 798 insertions(+), 100 deletions(-)

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index 85cf68fb4f7..b2dc6242fdf 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -76,6 +76,7 @@ jobs:
         with:
           key: build-${{ github.sha }}
           path: ${{ env.BUILD-CACHE-LIST }}
+      - run: npx playwright install --with-deps chromium
       - run: yarn test
 
   lint:
diff --git a/packages/graphiql-react/.storybook/main.ts b/packages/graphiql-react/.storybook/main.ts
index cf7d1305e8a..dddd2d457b7 100644
--- a/packages/graphiql-react/.storybook/main.ts
+++ b/packages/graphiql-react/.storybook/main.ts
@@ -2,7 +2,7 @@ import type { StorybookConfig } from '@storybook/react-vite';
 
 const config: StorybookConfig = {
   stories: ['../src/**/*.stories.@(ts|tsx)'],
-  addons: [],
+  addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
   framework: { name: '@storybook/react-vite', options: {} },
 };
 
diff --git a/packages/graphiql-react/.storybook/preview.tsx b/packages/graphiql-react/.storybook/preview.tsx
index 2c975d64305..8004f881823 100644
--- a/packages/graphiql-react/.storybook/preview.tsx
+++ b/packages/graphiql-react/.storybook/preview.tsx
@@ -4,6 +4,7 @@ import '../src/style/root.css';
 const preview: Preview = {
   parameters: {
     backgrounds: { disable: true },
+    a11y: { test: 'error' },
   },
   globalTypes: {
     theme: {
diff --git a/packages/graphiql-react/package.json b/packages/graphiql-react/package.json
index dadd8ed9108..8b2046f044e 100644
--- a/packages/graphiql-react/package.json
+++ b/packages/graphiql-react/package.json
@@ -72,14 +72,18 @@
   },
   "devDependencies": {
     "@babel/helper-string-parser": "^7.19.4",
+    "@storybook/addon-a11y": "^10.3.6",
+    "@storybook/addon-vitest": "^10.3.6",
     "@storybook/react-vite": "^10.3.6",
     "@types/get-value": "^3.0.5",
     "@types/markdown-it": "^14.1.2",
     "@types/react-dom": "^19.1.2",
     "@types/set-value": "^4.0.1",
     "@vitejs/plugin-react": "^4.4.1",
+    "@vitest/browser-playwright": "^4.1.6",
     "babel-plugin-react-compiler": "19.1.0-rc.1",
     "graphql": "^16.9.0",
+    "playwright": "^1.60.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "storybook": "^10.3.6",
diff --git a/packages/graphiql-react/vitest.config.mts b/packages/graphiql-react/vitest.config.mts
index 1127e2b1b9b..f3b0d2bb908 100644
--- a/packages/graphiql-react/vitest.config.mts
+++ b/packages/graphiql-react/vitest.config.mts
@@ -1,19 +1,47 @@
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vitest/config';
+import { playwright } from '@vitest/browser-playwright';
+import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
 import { plugins } from './vite.config.mjs';
 
+const dirname = path.dirname(fileURLToPath(import.meta.url));
+
 export default defineConfig({
   plugins,
   test: {
-    environment: 'jsdom',
-    setupFiles: ['./setup-files.ts'],
-    alias: [
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: 'unit',
+          environment: 'jsdom',
+          setupFiles: ['./setup-files.ts'],
+          alias: [
+            {
+              // Fixes Error: Failed to resolve entry for package "monaco-editor". The package may have incorrect main/module/exports specified in its package.json.
+              find: /^monaco-editor$/,
+              replacement: path.resolve(
+                '../../node_modules/monaco-editor/esm/vs/editor/editor.api',
+              ),
+            },
+          ],
+        },
+      },
       {
-        // Fixes Error: Failed to resolve entry for package "monaco-editor". The package may have incorrect main/module/exports specified in its package.json.
-        find: /^monaco-editor$/,
-        replacement: path.resolve(
-          '../../node_modules/monaco-editor/esm/vs/editor/editor.api',
-        ),
+        extends: true,
+        plugins: [
+          storybookTest({ configDir: path.join(dirname, '.storybook') }),
+        ],
+        test: {
+          name: 'storybook',
+          browser: {
+            enabled: true,
+            headless: true,
+            provider: playwright({}),
+            instances: [{ browser: 'chromium' }],
+          },
+        },
       },
     ],
   },
diff --git a/yarn.lock b/yarn.lock
index ce298d188f2..0fe13ea2029 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1003,8 +1003,8 @@ __metadata:
   linkType: hard
 
 "@babel/plugin-transform-modules-systemjs@npm:^7.29.0":
-  version: 7.29.4
-  resolution: "@babel/plugin-transform-modules-systemjs@npm:7.29.4"
+  version: 7.29.0
+  resolution: "@babel/plugin-transform-modules-systemjs@npm:7.29.0"
   dependencies:
     "@babel/helper-module-transforms": "npm:^7.28.6"
     "@babel/helper-plugin-utils": "npm:^7.28.6"
@@ -1012,7 +1012,7 @@ __metadata:
     "@babel/traverse": "npm:^7.29.0"
   peerDependencies:
     "@babel/core": ^7.0.0-0
-  checksum: 10c0/1da94f89ef8ba1aa1501136a80eb4c010c6a19f5550e10db84677b3ccb7a4934c8098f2b5134def87cf513bf05747ffa523d33722a1ea5a5c8ef956e9136c4c2
+  checksum: 10c0/44ea502f2c990398b7d9adc5b44d9e1810a0a5e86eebc05c92d039458f0b3994fe243efa9353b90f8a648d8a91b79845fb353d8679d7324cc9de0162d732771d
   languageName: node
   linkType: hard
 
@@ -1587,6 +1587,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@blazediff/core@npm:1.9.1":
+  version: 1.9.1
+  resolution: "@blazediff/core@npm:1.9.1"
+  checksum: 10c0/fd45cdd0544002341d74831a179ef693a81414abd348c1ff0c01086c0ea03f5e5ee284c4e16c2e6fb3670c265f90a3d85752b9360320efa9a835928e604dae77
+  languageName: node
+  linkType: hard
+
 "@bramus/specificity@npm:^2.4.2":
   version: 2.4.2
   resolution: "@bramus/specificity@npm:2.4.2"
@@ -2379,6 +2386,25 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@emnapi/core@npm:1.9.2":
+  version: 1.9.2
+  resolution: "@emnapi/core@npm:1.9.2"
+  dependencies:
+    "@emnapi/wasi-threads": "npm:1.2.1"
+    tslib: "npm:^2.4.0"
+  checksum: 10c0/5500393f953951bad0768fafaa9191f2d938956b20c6d6a79e5ab696a613a25ce6ad23422bc18e86e6ce8deb147619d8d0d7d413a69f84adc01a6633cc353cd9
+  languageName: node
+  linkType: hard
+
+"@emnapi/runtime@npm:1.9.2":
+  version: 1.9.2
+  resolution: "@emnapi/runtime@npm:1.9.2"
+  dependencies:
+    tslib: "npm:^2.4.0"
+  checksum: 10c0/61c3a59e0c36784558b8d58eb02bd04815aa5fb0dbfbaf84d1b3050a78aa0cc63ea129ae806bd1e48062bfeb7fc36eb0e5431740d62f64ea51bdf426404b8caa
+  languageName: node
+  linkType: hard
+
 "@emnapi/runtime@npm:^1.7.0":
   version: 1.10.0
   resolution: "@emnapi/runtime@npm:1.10.0"
@@ -2388,6 +2414,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@emnapi/wasi-threads@npm:1.2.1":
+  version: 1.2.1
+  resolution: "@emnapi/wasi-threads@npm:1.2.1"
+  dependencies:
+    tslib: "npm:^2.4.0"
+  checksum: 10c0/32fcfa81ab396533b2ec1f4082b1ff779a05d9c836bbbd3f4398405b0e6814c0d9503b7993130e37bc6941dbc1ded49f55e9700ae9ca4e803bab2b5bc5deb331
+  languageName: node
+  linkType: hard
+
 "@envelop/core@npm:^5.4.0":
   version: 5.5.1
   resolution: "@envelop/core@npm:5.5.1"
@@ -3291,12 +3326,15 @@ __metadata:
     "@radix-ui/react-dropdown-menu": "npm:^2.1"
     "@radix-ui/react-tooltip": "npm:^1.2"
     "@radix-ui/react-visually-hidden": "npm:^1.2"
+    "@storybook/addon-a11y": "npm:^10.3.6"
+    "@storybook/addon-vitest": "npm:^10.3.6"
     "@storybook/react-vite": "npm:^10.3.6"
     "@types/get-value": "npm:^3.0.5"
     "@types/markdown-it": "npm:^14.1.2"
     "@types/react-dom": "npm:^19.1.2"
     "@types/set-value": "npm:^4.0.1"
     "@vitejs/plugin-react": "npm:^4.4.1"
+    "@vitest/browser-playwright": "npm:^4.1.6"
     babel-plugin-react-compiler: "npm:19.1.0-rc.1"
     clsx: "npm:^1.2.1"
     framer-motion: "npm:^12.12"
@@ -3307,6 +3345,7 @@ __metadata:
     markdown-it: "npm:^14.1.0"
     monaco-editor: "npm:0.52.2"
     monaco-graphql: "npm:^1.7.4"
+    playwright: "npm:^1.60.0"
     prettier: "npm:^3.5.3"
     react: "npm:^19.1.0"
     react-compiler-runtime: "npm:19.1.0-rc.1"
@@ -4276,65 +4315,77 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@next/env@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/env@npm:15.5.18"
-  checksum: 10c0/cfb628f88b903b2593a778658abd2eed8a35ca91807ef19c08461543ed3ba9143e6f0ea4f29b98693f806f9498d1e6ca7c1efd1e0c3a0595991e2bac202e545a
+"@napi-rs/wasm-runtime@npm:^1.1.1, @napi-rs/wasm-runtime@npm:^1.1.4":
+  version: 1.1.4
+  resolution: "@napi-rs/wasm-runtime@npm:1.1.4"
+  dependencies:
+    "@tybys/wasm-util": "npm:^0.10.1"
+  peerDependencies:
+    "@emnapi/core": ^1.7.1
+    "@emnapi/runtime": ^1.7.1
+  checksum: 10c0/2e88e1955258949ccf2d18c79975821ad38071b465ef126a5e14110977b97868867b016c1ad046e963cccc42c0bd9db6c8ff5fd1ebb61b87bb3487f339041658
+  languageName: node
+  linkType: hard
+
+"@next/env@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/env@npm:15.5.15"
+  checksum: 10c0/f22ceea51866896ba0b981c74283b4637b109100efa3a3b5ed2cd0943fb7e0434fb686185a33c6dee2ede4801a4e071b6e50526bbff54cdbdc0973dfd149883f
   languageName: node
   linkType: hard
 
-"@next/swc-darwin-arm64@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-darwin-arm64@npm:15.5.18"
+"@next/swc-darwin-arm64@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-darwin-arm64@npm:15.5.15"
   conditions: os=darwin & cpu=arm64
   languageName: node
   linkType: hard
 
-"@next/swc-darwin-x64@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-darwin-x64@npm:15.5.18"
+"@next/swc-darwin-x64@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-darwin-x64@npm:15.5.15"
   conditions: os=darwin & cpu=x64
   languageName: node
   linkType: hard
 
-"@next/swc-linux-arm64-gnu@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-linux-arm64-gnu@npm:15.5.18"
+"@next/swc-linux-arm64-gnu@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-linux-arm64-gnu@npm:15.5.15"
   conditions: os=linux & cpu=arm64 & libc=glibc
   languageName: node
   linkType: hard
 
-"@next/swc-linux-arm64-musl@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-linux-arm64-musl@npm:15.5.18"
+"@next/swc-linux-arm64-musl@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-linux-arm64-musl@npm:15.5.15"
   conditions: os=linux & cpu=arm64 & libc=musl
   languageName: node
   linkType: hard
 
-"@next/swc-linux-x64-gnu@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-linux-x64-gnu@npm:15.5.18"
+"@next/swc-linux-x64-gnu@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-linux-x64-gnu@npm:15.5.15"
   conditions: os=linux & cpu=x64 & libc=glibc
   languageName: node
   linkType: hard
 
-"@next/swc-linux-x64-musl@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-linux-x64-musl@npm:15.5.18"
+"@next/swc-linux-x64-musl@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-linux-x64-musl@npm:15.5.15"
   conditions: os=linux & cpu=x64 & libc=musl
   languageName: node
   linkType: hard
 
-"@next/swc-win32-arm64-msvc@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-win32-arm64-msvc@npm:15.5.18"
+"@next/swc-win32-arm64-msvc@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-win32-arm64-msvc@npm:15.5.15"
   conditions: os=win32 & cpu=arm64
   languageName: node
   linkType: hard
 
-"@next/swc-win32-x64-msvc@npm:15.5.18":
-  version: 15.5.18
-  resolution: "@next/swc-win32-x64-msvc@npm:15.5.18"
+"@next/swc-win32-x64-msvc@npm:15.5.15":
+  version: 15.5.15
+  resolution: "@next/swc-win32-x64-msvc@npm:15.5.15"
   conditions: os=win32 & cpu=x64
   languageName: node
   linkType: hard
@@ -4433,6 +4484,299 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@oxc-parser/binding-android-arm-eabi@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-android-arm-eabi@npm:0.127.0"
+  conditions: os=android & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-android-arm64@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-android-arm64@npm:0.127.0"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-darwin-arm64@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-darwin-arm64@npm:0.127.0"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-darwin-x64@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-darwin-x64@npm:0.127.0"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-freebsd-x64@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-freebsd-x64@npm:0.127.0"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-arm-gnueabihf@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-arm-gnueabihf@npm:0.127.0"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-arm-musleabihf@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-arm-musleabihf@npm:0.127.0"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-arm64-gnu@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-arm64-gnu@npm:0.127.0"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-arm64-musl@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-arm64-musl@npm:0.127.0"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-ppc64-gnu@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-ppc64-gnu@npm:0.127.0"
+  conditions: os=linux & cpu=ppc64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-riscv64-gnu@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-riscv64-gnu@npm:0.127.0"
+  conditions: os=linux & cpu=riscv64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-riscv64-musl@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-riscv64-musl@npm:0.127.0"
+  conditions: os=linux & cpu=riscv64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-s390x-gnu@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-s390x-gnu@npm:0.127.0"
+  conditions: os=linux & cpu=s390x & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-x64-gnu@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-x64-gnu@npm:0.127.0"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-linux-x64-musl@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-linux-x64-musl@npm:0.127.0"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-openharmony-arm64@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-openharmony-arm64@npm:0.127.0"
+  conditions: os=openharmony & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-wasm32-wasi@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-wasm32-wasi@npm:0.127.0"
+  dependencies:
+    "@emnapi/core": "npm:1.9.2"
+    "@emnapi/runtime": "npm:1.9.2"
+    "@napi-rs/wasm-runtime": "npm:^1.1.4"
+  conditions: cpu=wasm32
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-win32-arm64-msvc@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-win32-arm64-msvc@npm:0.127.0"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-win32-ia32-msvc@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-win32-ia32-msvc@npm:0.127.0"
+  conditions: os=win32 & cpu=ia32
+  languageName: node
+  linkType: hard
+
+"@oxc-parser/binding-win32-x64-msvc@npm:0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-parser/binding-win32-x64-msvc@npm:0.127.0"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@oxc-project/types@npm:^0.127.0":
+  version: 0.127.0
+  resolution: "@oxc-project/types@npm:0.127.0"
+  checksum: 10c0/52c0947ac64a9ca119fe971f947e784a35ecd14a072fa3f542a58a5f6c42010b53f2bf92731e39b9899b83c990a9517bbd29d1e5a5b7b489e52616685c6a9278
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-android-arm-eabi@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-android-arm-eabi@npm:11.19.1"
+  conditions: os=android & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-android-arm64@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-android-arm64@npm:11.19.1"
+  conditions: os=android & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-darwin-arm64@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-darwin-arm64@npm:11.19.1"
+  conditions: os=darwin & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-darwin-x64@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-darwin-x64@npm:11.19.1"
+  conditions: os=darwin & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-freebsd-x64@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-freebsd-x64@npm:11.19.1"
+  conditions: os=freebsd & cpu=x64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-arm-gnueabihf@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-arm-gnueabihf@npm:11.19.1"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-arm-musleabihf@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-arm-musleabihf@npm:11.19.1"
+  conditions: os=linux & cpu=arm
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-arm64-gnu@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-arm64-gnu@npm:11.19.1"
+  conditions: os=linux & cpu=arm64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-arm64-musl@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-arm64-musl@npm:11.19.1"
+  conditions: os=linux & cpu=arm64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-ppc64-gnu@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-ppc64-gnu@npm:11.19.1"
+  conditions: os=linux & cpu=ppc64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-riscv64-gnu@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-riscv64-gnu@npm:11.19.1"
+  conditions: os=linux & cpu=riscv64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-riscv64-musl@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-riscv64-musl@npm:11.19.1"
+  conditions: os=linux & cpu=riscv64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-s390x-gnu@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-s390x-gnu@npm:11.19.1"
+  conditions: os=linux & cpu=s390x & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-x64-gnu@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-x64-gnu@npm:11.19.1"
+  conditions: os=linux & cpu=x64 & libc=glibc
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-linux-x64-musl@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-linux-x64-musl@npm:11.19.1"
+  conditions: os=linux & cpu=x64 & libc=musl
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-openharmony-arm64@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-openharmony-arm64@npm:11.19.1"
+  conditions: os=openharmony & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-wasm32-wasi@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-wasm32-wasi@npm:11.19.1"
+  dependencies:
+    "@napi-rs/wasm-runtime": "npm:^1.1.1"
+  conditions: cpu=wasm32
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-win32-arm64-msvc@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-win32-arm64-msvc@npm:11.19.1"
+  conditions: os=win32 & cpu=arm64
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-win32-ia32-msvc@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-win32-ia32-msvc@npm:11.19.1"
+  conditions: os=win32 & cpu=ia32
+  languageName: node
+  linkType: hard
+
+"@oxc-resolver/binding-win32-x64-msvc@npm:11.19.1":
+  version: 11.19.1
+  resolution: "@oxc-resolver/binding-win32-x64-msvc@npm:11.19.1"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@oxfmt/binding-android-arm-eabi@npm:0.45.0":
   version: 0.45.0
   resolution: "@oxfmt/binding-android-arm-eabi@npm:0.45.0"
@@ -4915,6 +5259,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@polka/url@npm:^1.0.0-next.24":
+  version: 1.0.0-next.29
+  resolution: "@polka/url@npm:1.0.0-next.29"
+  checksum: 10c0/0d58e081844095cb029d3c19a659bfefd09d5d51a2f791bc61eba7ea826f13d6ee204a8a448c2f5a855c17df07b37517373ff916dd05801063c0568ae9937684
+  languageName: node
+  linkType: hard
+
 "@radix-ui/primitive@npm:1.1.2":
   version: 1.1.2
   resolution: "@radix-ui/primitive@npm:1.1.2"
@@ -6059,28 +6410,65 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/builder-vite@npm:10.3.6":
-  version: 10.3.6
-  resolution: "@storybook/builder-vite@npm:10.3.6"
+"@storybook/addon-a11y@npm:^10.3.6":
+  version: 10.4.0
+  resolution: "@storybook/addon-a11y@npm:10.4.0"
   dependencies:
-    "@storybook/csf-plugin": "npm:10.3.6"
+    "@storybook/global": "npm:^5.0.0"
+    axe-core: "npm:^4.2.0"
+  peerDependencies:
+    storybook: ^10.4.0
+  checksum: 10c0/f018fb5aa7edbba00657c57eae32aaecf85b7f4063d9da0f4cb97975f4f3a7b0d347bfdca167ef91127dfecaefdaf10c59337109a5ce2c8811329d4cceaa67c8
+  languageName: node
+  linkType: hard
+
+"@storybook/addon-vitest@npm:^10.3.6":
+  version: 10.4.0
+  resolution: "@storybook/addon-vitest@npm:10.4.0"
+  dependencies:
+    "@storybook/global": "npm:^5.0.0"
+    "@storybook/icons": "npm:^2.0.2"
+  peerDependencies:
+    "@vitest/browser": ^3.0.0 || ^4.0.0
+    "@vitest/browser-playwright": ^4.0.0
+    "@vitest/runner": ^3.0.0 || ^4.0.0
+    storybook: ^10.4.0
+    vitest: ^3.0.0 || ^4.0.0
+  peerDependenciesMeta:
+    "@vitest/browser":
+      optional: true
+    "@vitest/browser-playwright":
+      optional: true
+    "@vitest/runner":
+      optional: true
+    vitest:
+      optional: true
+  checksum: 10c0/01bd3fb79af3fa3cb026cf13a0df2b5f87dc2283ad95a176b243a62427a6fba7359d25daa78b922f834e4e4ebc7f839950e762a7d320b8f6eca698766f4ebdbd
+  languageName: node
+  linkType: hard
+
+"@storybook/builder-vite@npm:10.4.0":
+  version: 10.4.0
+  resolution: "@storybook/builder-vite@npm:10.4.0"
+  dependencies:
+    "@storybook/csf-plugin": "npm:10.4.0"
     ts-dedent: "npm:^2.0.0"
   peerDependencies:
-    storybook: ^10.3.6
+    storybook: ^10.4.0
     vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
-  checksum: 10c0/f7e5c57362ba8df8dac4f71dc86d4117cd1edfaf2f61a3ecb0d6bece6b37357f1dc0bf135fd27b5552055b47e0fce5ffba67ffeb2fdedbc75fc986997062bf28
+  checksum: 10c0/416240f36b7e93520a6d1168470614fce615062c3c39ea1ad9fe1defffc4f50716b2923210d4e89fa68c1162d89a6f646ef29a08759ed2430ccbf1c0c89453b6
   languageName: node
   linkType: hard
 
-"@storybook/csf-plugin@npm:10.3.6":
-  version: 10.3.6
-  resolution: "@storybook/csf-plugin@npm:10.3.6"
+"@storybook/csf-plugin@npm:10.4.0":
+  version: 10.4.0
+  resolution: "@storybook/csf-plugin@npm:10.4.0"
   dependencies:
     unplugin: "npm:^2.3.5"
   peerDependencies:
     esbuild: "*"
     rollup: "*"
-    storybook: ^10.3.6
+    storybook: ^10.4.0
     vite: "*"
     webpack: "*"
   peerDependenciesMeta:
@@ -6092,7 +6480,7 @@ __metadata:
       optional: true
     webpack:
       optional: true
-  checksum: 10c0/593fc6b9b6073c9dacd26f595ccb58f1ac28f3ab3cf63bf3d8d6913285765eb9c4fdb3e1c54356804ec8eccdde24f14cfa7af3e528731eb6d7e52266d81c4213
+  checksum: 10c0/9c968636b14beb9b740b42c3e0f0b81ef2662344bb2328e1149b62e71d3e1e45d82bb08788b6a3fe7755c2884d0b5cf8e033937a07659047764dcfeb91cce80b
   languageName: node
   linkType: hard
 
@@ -6103,7 +6491,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/icons@npm:^2.0.1":
+"@storybook/icons@npm:^2.0.2":
   version: 2.0.2
   resolution: "@storybook/icons@npm:2.0.2"
   peerDependencies:
@@ -6113,25 +6501,32 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@storybook/react-dom-shim@npm:10.3.6":
-  version: 10.3.6
-  resolution: "@storybook/react-dom-shim@npm:10.3.6"
+"@storybook/react-dom-shim@npm:10.4.0":
+  version: 10.4.0
+  resolution: "@storybook/react-dom-shim@npm:10.4.0"
   peerDependencies:
+    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    "@types/react-dom": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.3.6
-  checksum: 10c0/60183fc05b0410ca174f215d3271ffbccdc2680bd0704f58dc931cf60e72f497a9f22c00afa868398ad693c7ec633ef619541d4b0611fc2a577fb09609fcc3c7
+    storybook: ^10.4.0
+  peerDependenciesMeta:
+    "@types/react":
+      optional: true
+    "@types/react-dom":
+      optional: true
+  checksum: 10c0/d2a07900dd7d35403abb29f23f0f58a53e552003c713a004b465bfc8a781399e3a6062682fe950b79faf5b45bb1955139abe69b6d9f4c3478688b30ebd669274
   languageName: node
   linkType: hard
 
 "@storybook/react-vite@npm:^10.3.6":
-  version: 10.3.6
-  resolution: "@storybook/react-vite@npm:10.3.6"
+  version: 10.4.0
+  resolution: "@storybook/react-vite@npm:10.4.0"
   dependencies:
     "@joshwooding/vite-plugin-react-docgen-typescript": "npm:^0.7.0"
     "@rollup/pluginutils": "npm:^5.0.2"
-    "@storybook/builder-vite": "npm:10.3.6"
-    "@storybook/react": "npm:10.3.6"
+    "@storybook/builder-vite": "npm:10.4.0"
+    "@storybook/react": "npm:10.4.0"
     empathic: "npm:^2.0.0"
     magic-string: "npm:^0.30.0"
     react-docgen: "npm:^8.0.0"
@@ -6140,29 +6535,35 @@ __metadata:
   peerDependencies:
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.3.6
+    storybook: ^10.4.0
     vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
-  checksum: 10c0/3b939caf05985f0c6d5049c49b71fd8c7abac1f94f1559cfa135a755f3d94c0ef29bdd8d7f7f68c4676ea66852ed4b43d2e33d18434aa1c72f4aebca928b3e13
+  checksum: 10c0/3674c84a59ab75df75bc56fcce9e50464bea05c0d02f6ff6733b734b57d6629b501844a4a9491f01df945eec8c65dd14d9d97552d45aaff49a9782453ee476cf
   languageName: node
   linkType: hard
 
-"@storybook/react@npm:10.3.6":
-  version: 10.3.6
-  resolution: "@storybook/react@npm:10.3.6"
+"@storybook/react@npm:10.4.0":
+  version: 10.4.0
+  resolution: "@storybook/react@npm:10.4.0"
   dependencies:
     "@storybook/global": "npm:^5.0.0"
-    "@storybook/react-dom-shim": "npm:10.3.6"
+    "@storybook/react-dom-shim": "npm:10.4.0"
     react-docgen: "npm:^8.0.2"
     react-docgen-typescript: "npm:^2.2.2"
   peerDependencies:
+    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    "@types/react-dom": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
-    storybook: ^10.3.6
+    storybook: ^10.4.0
     typescript: ">= 4.9.x"
   peerDependenciesMeta:
+    "@types/react":
+      optional: true
+    "@types/react-dom":
+      optional: true
     typescript:
       optional: true
-  checksum: 10c0/3d3af66105cdca98c537b4bcc3e92f87e3b56d154b24e9b167300e9d5de8a7ba6a5ef3c22203ccb6f4c2f0602a5546273b2b49728aa383ba0f98e66a286647a8
+  checksum: 10c0/b23acb83cb5eccd0b37eb2a73158ed444b702f7e484277e6e65ac05d18dff2c3b1dd45c00941a86e7acd4ba3edfe14f79448c9316915426dbce2752ecceeaa5e
   languageName: node
   linkType: hard
 
@@ -6410,6 +6811,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@tybys/wasm-util@npm:^0.10.1":
+  version: 0.10.2
+  resolution: "@tybys/wasm-util@npm:0.10.2"
+  dependencies:
+    tslib: "npm:^2.4.0"
+  checksum: 10c0/26165bcd1fd7269f42d7fbe3de318f854a8968de8397e89fc9a423bb3e2da35a52150f382e6323b3367595beb16d9800a6f35971a5599daf76da1742ec3afc25
+  languageName: node
+  linkType: hard
+
 "@types/argparse@npm:1.0.38":
   version: 1.0.38
   resolution: "@types/argparse@npm:1.0.38"
@@ -7232,6 +7642,41 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@vitest/browser-playwright@npm:^4.1.6":
+  version: 4.1.6
+  resolution: "@vitest/browser-playwright@npm:4.1.6"
+  dependencies:
+    "@vitest/browser": "npm:4.1.6"
+    "@vitest/mocker": "npm:4.1.6"
+    tinyrainbow: "npm:^3.1.0"
+  peerDependencies:
+    playwright: "*"
+    vitest: 4.1.6
+  peerDependenciesMeta:
+    playwright:
+      optional: false
+  checksum: 10c0/501d78e0a56004d9b2fc7f86177d8cb3a9cf2ed1a7a7b075d5b536e29c27bb909f8df418eafbdcdf1cc6dff1faa5a02b0cddd822bc1210e61f25e587a1e2af8e
+  languageName: node
+  linkType: hard
+
+"@vitest/browser@npm:4.1.6":
+  version: 4.1.6
+  resolution: "@vitest/browser@npm:4.1.6"
+  dependencies:
+    "@blazediff/core": "npm:1.9.1"
+    "@vitest/mocker": "npm:4.1.6"
+    "@vitest/utils": "npm:4.1.6"
+    magic-string: "npm:^0.30.21"
+    pngjs: "npm:^7.0.0"
+    sirv: "npm:^3.0.2"
+    tinyrainbow: "npm:^3.1.0"
+    ws: "npm:^8.19.0"
+  peerDependencies:
+    vitest: 4.1.6
+  checksum: 10c0/f9e8dd7e48add4d11856517bfdbb6b0f9fa291d5b22bb21a5a74194f5b37e32e3597c653e59b630ac2c58f0edd70a440a17b12c1d03e867a5a26fd57ab9a3d67
+  languageName: node
+  linkType: hard
+
 "@vitest/expect@npm:3.2.4":
   version: 3.2.4
   resolution: "@vitest/expect@npm:3.2.4"
@@ -8629,7 +9074,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"axe-core@npm:^4":
+"axe-core@npm:^4, axe-core@npm:^4.2.0":
   version: 4.11.4
   resolution: "axe-core@npm:4.11.4"
   checksum: 10c0/c4aa83fc3eac5f7a0d0cb1a28f9d073acf0c06ce8daacc38608faa278c57ce084c028c850746b98817ae4c101c30c1a32e95ea34748c4b4c7419b9b81221ef84
@@ -9302,9 +9747,9 @@ __metadata:
   linkType: hard
 
 "check-error@npm:^2.1.1":
-  version: 2.1.1
-  resolution: "check-error@npm:2.1.1"
-  checksum: 10c0/979f13eccab306cf1785fa10941a590b4e7ea9916ea2a4f8c87f0316fc3eab07eabefb6e587424ef0f88cbcd3805791f172ea739863ca3d7ce2afc54641c7f0e
+  version: 2.1.3
+  resolution: "check-error@npm:2.1.3"
+  checksum: 10c0/878e99038fb6476316b74668cd6a498c7e66df3efe48158fa40db80a06ba4258742ac3ee2229c4a2a98c5e73f5dff84eb3e50ceb6b65bbd8f831eafc8338607d
   languageName: node
   linkType: hard
 
@@ -12312,9 +12757,9 @@ __metadata:
   linkType: hard
 
 "fast-uri@npm:^3.0.1":
-  version: 3.1.2
-  resolution: "fast-uri@npm:3.1.2"
-  checksum: 10c0/5b35641895959f3f7ab7a7b1b5542bded159346f25ec9f256817b206d50b64eda5828e90d605a2e2fc645c90519a7259c2bab2c942ee728c88b88e5be21b090d
+  version: 3.0.3
+  resolution: "fast-uri@npm:3.0.3"
+  checksum: 10c0/4b2c5ce681a062425eae4f15cdc8fc151fd310b2f69b1f96680677820a8b49c3cd6e80661a406e19d50f0c40a3f8bffdd458791baf66f4a879d80be28e10a320
   languageName: node
   linkType: hard
 
@@ -12922,6 +13367,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fsevents@npm:2.3.2":
+  version: 2.3.2
+  resolution: "fsevents@npm:2.3.2"
+  dependencies:
+    node-gyp: "npm:latest"
+  checksum: 10c0/be78a3efa3e181cda3cf7a4637cb527bcebb0bd0ea0440105a3bb45b86f9245b307dc10a2507e8f4498a7d4ec349d1910f4d73e4d4495b16103106e07eee735b
+  conditions: os=darwin
+  languageName: node
+  linkType: hard
+
 "fsevents@npm:^1.1.1":
   version: 1.2.13
   resolution: "fsevents@npm:1.2.13"
@@ -12943,6 +13398,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fsevents@patch:fsevents@npm%3A2.3.2#optional!builtin<compat/fsevents>":
+  version: 2.3.2
+  resolution: "fsevents@patch:fsevents@npm%3A2.3.2#optional!builtin<compat/fsevents>::version=2.3.2&hash=df0bf1"
+  dependencies:
+    node-gyp: "npm:latest"
+  conditions: os=darwin
+  languageName: node
+  linkType: hard
+
 "fsevents@patch:fsevents@npm%3A^1.1.1#optional!builtin<compat/fsevents>":
   version: 1.2.13
   resolution: "fsevents@patch:fsevents@npm%3A1.2.13#optional!builtin<compat/fsevents>::version=1.2.13&hash=d11327"
@@ -16706,6 +17170,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"mrmime@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "mrmime@npm:2.0.1"
+  checksum: 10c0/af05afd95af202fdd620422f976ad67dc18e6ee29beb03dd1ce950ea6ef664de378e44197246df4c7cdd73d47f2e7143a6e26e473084b9e4aa2095c0ad1e1761
+  languageName: node
+  linkType: hard
+
 "ms@npm:2.0.0":
   version: 2.0.0
   resolution: "ms@npm:2.0.0"
@@ -16876,18 +17347,18 @@ __metadata:
   linkType: soft
 
 "next@npm:^15":
-  version: 15.5.18
-  resolution: "next@npm:15.5.18"
-  dependencies:
-    "@next/env": "npm:15.5.18"
-    "@next/swc-darwin-arm64": "npm:15.5.18"
-    "@next/swc-darwin-x64": "npm:15.5.18"
-    "@next/swc-linux-arm64-gnu": "npm:15.5.18"
-    "@next/swc-linux-arm64-musl": "npm:15.5.18"
-    "@next/swc-linux-x64-gnu": "npm:15.5.18"
-    "@next/swc-linux-x64-musl": "npm:15.5.18"
-    "@next/swc-win32-arm64-msvc": "npm:15.5.18"
-    "@next/swc-win32-x64-msvc": "npm:15.5.18"
+  version: 15.5.15
+  resolution: "next@npm:15.5.15"
+  dependencies:
+    "@next/env": "npm:15.5.15"
+    "@next/swc-darwin-arm64": "npm:15.5.15"
+    "@next/swc-darwin-x64": "npm:15.5.15"
+    "@next/swc-linux-arm64-gnu": "npm:15.5.15"
+    "@next/swc-linux-arm64-musl": "npm:15.5.15"
+    "@next/swc-linux-x64-gnu": "npm:15.5.15"
+    "@next/swc-linux-x64-musl": "npm:15.5.15"
+    "@next/swc-win32-arm64-msvc": "npm:15.5.15"
+    "@next/swc-win32-x64-msvc": "npm:15.5.15"
     "@swc/helpers": "npm:0.5.15"
     caniuse-lite: "npm:^1.0.30001579"
     postcss: "npm:8.4.31"
@@ -16930,7 +17401,7 @@ __metadata:
       optional: true
   bin:
     next: dist/bin/next
-  checksum: 10c0/94c3be1ee04240913ab9d46e70fde3b26a73cedf6c76e946cfd2580d7ddd494b7da66260fe3a9a2be187652f5a10b1d9a6a555f10744d350be7f6ae05157d893
+  checksum: 10c0/580750feebdf3035478816dcd819d216193ea0873b1f2844790b271235790129b5e8364499256a825d9b493baeddf94a39d05691f1b17ae418f39571a2381bbc
   languageName: node
   linkType: hard
 
@@ -17389,6 +17860,145 @@ __metadata:
   languageName: node
   linkType: hard
 
+"oxc-parser@npm:^0.127.0":
+  version: 0.127.0
+  resolution: "oxc-parser@npm:0.127.0"
+  dependencies:
+    "@oxc-parser/binding-android-arm-eabi": "npm:0.127.0"
+    "@oxc-parser/binding-android-arm64": "npm:0.127.0"
+    "@oxc-parser/binding-darwin-arm64": "npm:0.127.0"
+    "@oxc-parser/binding-darwin-x64": "npm:0.127.0"
+    "@oxc-parser/binding-freebsd-x64": "npm:0.127.0"
+    "@oxc-parser/binding-linux-arm-gnueabihf": "npm:0.127.0"
+    "@oxc-parser/binding-linux-arm-musleabihf": "npm:0.127.0"
+    "@oxc-parser/binding-linux-arm64-gnu": "npm:0.127.0"
+    "@oxc-parser/binding-linux-arm64-musl": "npm:0.127.0"
+    "@oxc-parser/binding-linux-ppc64-gnu": "npm:0.127.0"
+    "@oxc-parser/binding-linux-riscv64-gnu": "npm:0.127.0"
+    "@oxc-parser/binding-linux-riscv64-musl": "npm:0.127.0"
+    "@oxc-parser/binding-linux-s390x-gnu": "npm:0.127.0"
+    "@oxc-parser/binding-linux-x64-gnu": "npm:0.127.0"
+    "@oxc-parser/binding-linux-x64-musl": "npm:0.127.0"
+    "@oxc-parser/binding-openharmony-arm64": "npm:0.127.0"
+    "@oxc-parser/binding-wasm32-wasi": "npm:0.127.0"
+    "@oxc-parser/binding-win32-arm64-msvc": "npm:0.127.0"
+    "@oxc-parser/binding-win32-ia32-msvc": "npm:0.127.0"
+    "@oxc-parser/binding-win32-x64-msvc": "npm:0.127.0"
+    "@oxc-project/types": "npm:^0.127.0"
+  dependenciesMeta:
+    "@oxc-parser/binding-android-arm-eabi":
+      optional: true
+    "@oxc-parser/binding-android-arm64":
+      optional: true
+    "@oxc-parser/binding-darwin-arm64":
+      optional: true
+    "@oxc-parser/binding-darwin-x64":
+      optional: true
+    "@oxc-parser/binding-freebsd-x64":
+      optional: true
+    "@oxc-parser/binding-linux-arm-gnueabihf":
+      optional: true
+    "@oxc-parser/binding-linux-arm-musleabihf":
+      optional: true
+    "@oxc-parser/binding-linux-arm64-gnu":
+      optional: true
+    "@oxc-parser/binding-linux-arm64-musl":
+      optional: true
+    "@oxc-parser/binding-linux-ppc64-gnu":
+      optional: true
+    "@oxc-parser/binding-linux-riscv64-gnu":
+      optional: true
+    "@oxc-parser/binding-linux-riscv64-musl":
+      optional: true
+    "@oxc-parser/binding-linux-s390x-gnu":
+      optional: true
+    "@oxc-parser/binding-linux-x64-gnu":
+      optional: true
+    "@oxc-parser/binding-linux-x64-musl":
+      optional: true
+    "@oxc-parser/binding-openharmony-arm64":
+      optional: true
+    "@oxc-parser/binding-wasm32-wasi":
+      optional: true
+    "@oxc-parser/binding-win32-arm64-msvc":
+      optional: true
+    "@oxc-parser/binding-win32-ia32-msvc":
+      optional: true
+    "@oxc-parser/binding-win32-x64-msvc":
+      optional: true
+  checksum: 10c0/9d109fb3a79c0862a36434cc01c8c0e8f6cf5f1efe9369e02d2183fd518479b10262cf092da2e7f8328befae446afa05ccf742ce12f8346d81429c8f2cdf1651
+  languageName: node
+  linkType: hard
+
+"oxc-resolver@npm:^11.19.1":
+  version: 11.19.1
+  resolution: "oxc-resolver@npm:11.19.1"
+  dependencies:
+    "@oxc-resolver/binding-android-arm-eabi": "npm:11.19.1"
+    "@oxc-resolver/binding-android-arm64": "npm:11.19.1"
+    "@oxc-resolver/binding-darwin-arm64": "npm:11.19.1"
+    "@oxc-resolver/binding-darwin-x64": "npm:11.19.1"
+    "@oxc-resolver/binding-freebsd-x64": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-arm-gnueabihf": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-arm-musleabihf": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-arm64-gnu": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-arm64-musl": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-ppc64-gnu": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-riscv64-gnu": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-riscv64-musl": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-s390x-gnu": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-x64-gnu": "npm:11.19.1"
+    "@oxc-resolver/binding-linux-x64-musl": "npm:11.19.1"
+    "@oxc-resolver/binding-openharmony-arm64": "npm:11.19.1"
+    "@oxc-resolver/binding-wasm32-wasi": "npm:11.19.1"
+    "@oxc-resolver/binding-win32-arm64-msvc": "npm:11.19.1"
+    "@oxc-resolver/binding-win32-ia32-msvc": "npm:11.19.1"
+    "@oxc-resolver/binding-win32-x64-msvc": "npm:11.19.1"
+  dependenciesMeta:
+    "@oxc-resolver/binding-android-arm-eabi":
+      optional: true
+    "@oxc-resolver/binding-android-arm64":
+      optional: true
+    "@oxc-resolver/binding-darwin-arm64":
+      optional: true
+    "@oxc-resolver/binding-darwin-x64":
+      optional: true
+    "@oxc-resolver/binding-freebsd-x64":
+      optional: true
+    "@oxc-resolver/binding-linux-arm-gnueabihf":
+      optional: true
+    "@oxc-resolver/binding-linux-arm-musleabihf":
+      optional: true
+    "@oxc-resolver/binding-linux-arm64-gnu":
+      optional: true
+    "@oxc-resolver/binding-linux-arm64-musl":
+      optional: true
+    "@oxc-resolver/binding-linux-ppc64-gnu":
+      optional: true
+    "@oxc-resolver/binding-linux-riscv64-gnu":
+      optional: true
+    "@oxc-resolver/binding-linux-riscv64-musl":
+      optional: true
+    "@oxc-resolver/binding-linux-s390x-gnu":
+      optional: true
+    "@oxc-resolver/binding-linux-x64-gnu":
+      optional: true
+    "@oxc-resolver/binding-linux-x64-musl":
+      optional: true
+    "@oxc-resolver/binding-openharmony-arm64":
+      optional: true
+    "@oxc-resolver/binding-wasm32-wasi":
+      optional: true
+    "@oxc-resolver/binding-win32-arm64-msvc":
+      optional: true
+    "@oxc-resolver/binding-win32-ia32-msvc":
+      optional: true
+    "@oxc-resolver/binding-win32-x64-msvc":
+      optional: true
+  checksum: 10c0/8ac4eaffa9c0bcbb9f4f4a2b43786457ec5a68684d8776cb78b5a15ce3d1a79d3e67262aa3c635f98a0c1cd6cd56a31fcb05bffb9a286100056e4ab06b928833
+  languageName: node
+  linkType: hard
+
 "oxfmt@npm:^0.45.0":
   version: 0.45.0
   resolution: "oxfmt@npm:0.45.0"
@@ -17987,9 +18597,9 @@ __metadata:
   linkType: hard
 
 "pathval@npm:^2.0.0":
-  version: 2.0.0
-  resolution: "pathval@npm:2.0.0"
-  checksum: 10c0/602e4ee347fba8a599115af2ccd8179836a63c925c23e04bd056d0674a64b39e3a081b643cc7bc0b84390517df2d800a46fcc5598d42c155fe4977095c2f77c5
+  version: 2.0.1
+  resolution: "pathval@npm:2.0.1"
+  checksum: 10c0/460f4709479fbf2c45903a65655fc8f0a5f6d808f989173aeef5fdea4ff4f303dc13f7870303999add60ec49d4c14733895c0a869392e9866f1091fa64fd7581
   languageName: node
   linkType: hard
 
@@ -18146,6 +18756,37 @@ __metadata:
   languageName: node
   linkType: hard
 
+"playwright-core@npm:1.60.0":
+  version: 1.60.0
+  resolution: "playwright-core@npm:1.60.0"
+  bin:
+    playwright-core: cli.js
+  checksum: 10c0/99ccd43923b6e9355e0723b7fe221e6326efd4687f8dafff951313662aea11db51f542a9c2122c704c445fb9baae1c9ec9fa6f895126bbddd9fe92313f6942c9
+  languageName: node
+  linkType: hard
+
+"playwright@npm:^1.60.0":
+  version: 1.60.0
+  resolution: "playwright@npm:1.60.0"
+  dependencies:
+    fsevents: "npm:2.3.2"
+    playwright-core: "npm:1.60.0"
+  dependenciesMeta:
+    fsevents:
+      optional: true
+  bin:
+    playwright: cli.js
+  checksum: 10c0/714ad76d85b4865d7e43c0012f9039800c1485373388973ed39d79339cee5ad467052d1e2f1eaeca107a1cb6e65342186a8578a4c3504853d84c3a691250d5db
+  languageName: node
+  linkType: hard
+
+"pngjs@npm:^7.0.0":
+  version: 7.0.0
+  resolution: "pngjs@npm:7.0.0"
+  checksum: 10c0/0d4c7a0fd476a9c33df7d0a2a73e1d56537628a668841f6995c2bca070cf30819f9254a64363266bc14ef2fee47659dd3b4f2b18eec7ab65143015139f497b38
+  languageName: node
+  linkType: hard
+
 "possible-typed-array-names@npm:^1.0.0":
   version: 1.0.0
   resolution: "possible-typed-array-names@npm:1.0.0"
@@ -19986,6 +20627,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"sirv@npm:^3.0.2":
+  version: 3.0.2
+  resolution: "sirv@npm:3.0.2"
+  dependencies:
+    "@polka/url": "npm:^1.0.0-next.24"
+    mrmime: "npm:^2.0.0"
+    totalist: "npm:^3.0.0"
+  checksum: 10c0/5930e4397afdb14fbae13751c3be983af4bda5c9aadec832607dc2af15a7162f7d518c71b30e83ae3644b9a24cea041543cc969e5fe2b80af6ce8ea3174b2d04
+  languageName: node
+  linkType: hard
+
 "slash@npm:^2.0.0":
   version: 2.0.0
   resolution: "slash@npm:2.0.0"
@@ -20370,11 +21022,11 @@ __metadata:
   linkType: hard
 
 "storybook@npm:^10.3.6":
-  version: 10.3.6
-  resolution: "storybook@npm:10.3.6"
+  version: 10.4.0
+  resolution: "storybook@npm:10.4.0"
   dependencies:
     "@storybook/global": "npm:^5.0.0"
-    "@storybook/icons": "npm:^2.0.1"
+    "@storybook/icons": "npm:^2.0.2"
     "@testing-library/jest-dom": "npm:^6.9.1"
     "@testing-library/user-event": "npm:^14.6.1"
     "@vitest/expect": "npm:3.2.4"
@@ -20382,21 +21034,26 @@ __metadata:
     "@webcontainer/env": "npm:^1.1.1"
     esbuild: "npm:^0.18.0 || ^0.19.0 || ^0.20.0 || ^0.21.0 || ^0.22.0 || ^0.23.0 || ^0.24.0 || ^0.25.0 || ^0.26.0 || ^0.27.0"
     open: "npm:^10.2.0"
+    oxc-parser: "npm:^0.127.0"
+    oxc-resolver: "npm:^11.19.1"
     recast: "npm:^0.23.5"
     semver: "npm:^7.7.3"
     use-sync-external-store: "npm:^1.5.0"
     ws: "npm:^8.18.0"
   peerDependencies:
+    "@types/react": ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
     prettier: ^2 || ^3
     vite-plus: ^0.1.15
   peerDependenciesMeta:
+    "@types/react":
+      optional: true
     prettier:
       optional: true
     vite-plus:
       optional: true
   bin:
     storybook: ./dist/bin/dispatcher.js
-  checksum: 10c0/ee6702667459ba2d49269ddd63a7281f17816fcdd4bacd338ed47a4a8e7ad65760c90d99f6b2dfdfd0a564bcfcab3c1ea05b50bf3aafc6b5b19a039a5da77870
+  checksum: 10c0/f6e493819b68dbf4a182cd31d5717db08481a25cfc8c4ab6139fbb70e039a9d4e6d54ff1f8280d3b6052a06ef32242d3753bd9cbbdf91392f4c65a92acf8cff6
   languageName: node
   linkType: hard
 
@@ -21262,6 +21919,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"totalist@npm:^3.0.0":
+  version: 3.0.1
+  resolution: "totalist@npm:3.0.1"
+  checksum: 10c0/4bb1fadb69c3edbef91c73ebef9d25b33bbf69afe1e37ce544d5f7d13854cda15e47132f3e0dc4cafe300ddb8578c77c50a65004d8b6e97e77934a69aa924863
+  languageName: node
+  linkType: hard
+
 "tough-cookie@npm:^4.1.3":
   version: 4.1.4
   resolution: "tough-cookie@npm:4.1.4"
@@ -23378,9 +24042,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ws@npm:>=8.7.0, ws@npm:^8.18.0, ws@npm:^8.18.3, ws@npm:^8.20.0":
-  version: 8.20.0
-  resolution: "ws@npm:8.20.0"
+"ws@npm:>=8.7.0, ws@npm:^8.18.0, ws@npm:^8.18.3, ws@npm:^8.19.0, ws@npm:^8.20.0":
+  version: 8.20.1
+  resolution: "ws@npm:8.20.1"
   peerDependencies:
     bufferutil: ^4.0.1
     utf-8-validate: ">=5.0.2"
@@ -23389,7 +24053,7 @@ __metadata:
       optional: true
     utf-8-validate:
       optional: true
-  checksum: 10c0/956ac5f11738c914089b65878b9223692ace77337ba55379ae68e1ecbeae9b47a0c6eb9403688f609999a58c80d83d99865fe0029b229d308b08c1ef93d4ea14
+  checksum: 10c0/ce162433218399cdedeb76fd33363d4d86a7d910058d4e3c679dce08cea65d6da6b39f11baa4d7808d024cf46ed88f6a05c17611621aaad8fc5e62edacc30c5d
   languageName: node
   linkType: hard
 

From bd773d3a245cd3a6a9e1595f7d2d686e2201c786 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 14 May 2026 23:08:07 -0700
Subject: [PATCH 08/38] v6: Restyle `Button` and `ToolbarButton` (#4276)

## Summary

- Migrate `Button`, `UnStyledButton`, `ToolbarButton`, and
`ExecuteButton` CSS to v6 OKLCH tokens.
- Add `variant?: 'default' | 'primary'` to `Button`; `primary` renders
the Run-button style.
- Switch `:focus` to `:focus-visible` on interactive states so the focus
ring no longer fires on mouse click. Aligns with [MDN
`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible)
and WCAG 2.4.7 (Focus Visible).
- Import `clsx` directly in `button` and `toolbar-button`, following the
leaf-module pattern from #4272. A follow-up PR will convert remaining
callers and remove the `cn` re-export.
- Add Storybook stories: `Primitives/Button` (Default, Primary, Success,
Error, Disabled) and `Primitives/ToolbarButton` (Default).

## Test plan

- [x] Open Storybook `Primitives/Button` and verify each variant matches
the design.
- [x] Tab into the buttons, then mouse-click them. Focus ring appears on
Tab only, not on click.
- [x] Open `Primitives/ToolbarButton`. Hover the icon button; a v6
tooltip appears.
- [x] Run `yarn dev:graphiql`. The Run button and toolbar buttons match
the new design.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-button-iconbutton.md       |  5 ++
 .../src/components/button/button.stories.tsx  | 32 ++++++++++
 .../src/components/button/index.css           | 58 ++++++++++++-------
 .../src/components/button/index.tsx           |  4 +-
 .../src/components/execute-button/index.css   | 18 +++---
 .../src/components/toolbar-button/index.css   | 15 ++++-
 .../src/components/toolbar-button/index.tsx   |  2 +-
 .../toolbar-button/toolbar-button.stories.tsx | 26 +++++++++
 resources/custom-words.txt                    |  1 +
 9 files changed, 129 insertions(+), 32 deletions(-)
 create mode 100644 .changeset/restyle-button-iconbutton.md
 create mode 100644 packages/graphiql-react/src/components/button/button.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/toolbar-button/toolbar-button.stories.tsx

diff --git a/.changeset/restyle-button-iconbutton.md b/.changeset/restyle-button-iconbutton.md
new file mode 100644
index 00000000000..9bd754c377f
--- /dev/null
+++ b/.changeset/restyle-button-iconbutton.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `Button` and `ToolbarButton` to the v6 OKLCH design tokens. Adds a `primary` variant to `Button` for the Run-button style. Storybook stories added for each variant. Props and behavior unchanged.
diff --git a/packages/graphiql-react/src/components/button/button.stories.tsx b/packages/graphiql-react/src/components/button/button.stories.tsx
new file mode 100644
index 00000000000..35138126609
--- /dev/null
+++ b/packages/graphiql-react/src/components/button/button.stories.tsx
@@ -0,0 +1,32 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from './';
+
+const meta: Meta<typeof Button> = {
+  title: 'Primitives/Button',
+  component: Button,
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+export const Default: Story = {
+  render: () => <Button>Button</Button>,
+};
+
+export const Primary: Story = {
+  render: () => <Button variant="primary">Run</Button>,
+};
+
+export const Success: Story = {
+  render: () => <Button state="success">Copied!</Button>,
+};
+
+export const Error: Story = {
+  render: () => <Button state="error">Failed</Button>,
+};
+
+export const Disabled: Story = {
+  render: () => <Button disabled>Button</Button>,
+};
diff --git a/packages/graphiql-react/src/components/button/index.css b/packages/graphiql-react/src/components/button/index.css
index 4716869d05a..646c489a840 100644
--- a/packages/graphiql-react/src/components/button/index.css
+++ b/packages/graphiql-react/src/components/button/index.css
@@ -1,50 +1,66 @@
 .graphiql-un-styled {
   all: unset;
-  border-radius: var(--border-radius-4);
+  border-radius: var(--radius-sm);
   cursor: pointer;
 
   &:hover {
-    background-color: hsla(var(--color-neutral), var(--alpha-background-light));
+    background-color: oklch(var(--bg-overlay));
   }
 
   &:active {
-    background-color: hsla(
-      var(--color-neutral),
-      var(--alpha-background-medium)
-    );
+    background-color: oklch(var(--bg-overlay) / 0.8);
   }
 
-  &:focus {
-    outline: hsla(var(--color-neutral), var(--alpha-background-heavy)) auto 1px;
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: 1px;
   }
 }
 
 .graphiql-button,
 button.graphiql-button {
-  background-color: hsla(var(--color-neutral), var(--alpha-background-light));
-  border: none;
-  border-radius: var(--border-radius-4);
-  color: hsl(var(--color-neutral));
+  background-color: oklch(var(--bg-subtle));
+  border: 1px solid oklch(var(--border-strong));
+  border-radius: var(--radius-sm);
+  color: oklch(var(--fg-default));
   cursor: pointer;
   font-size: var(--font-size-body);
-  padding: var(--px-8) var(--px-12);
+  padding: var(--px-4) var(--px-12);
 
   &:hover,
   &:active {
-    background-color: hsla(
-      var(--color-neutral),
-      var(--alpha-background-medium)
-    );
+    background-color: oklch(var(--bg-overlay));
   }
 
-  &:focus {
-    outline: hsla(var(--color-neutral), var(--alpha-background-heavy)) auto 1px;
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: 1px;
+  }
+
+  &.graphiql-button-primary {
+    background-color: oklch(var(--btn-primary));
+    border-color: oklch(var(--btn-primary-border));
+    color: #fff;
+    font-weight: 600;
+
+    &:hover {
+      background-color: oklch(var(--btn-primary-border));
+    }
+
+    &:active {
+      background-color: oklch(var(--btn-primary));
+      opacity: 0.85;
+    }
   }
 
   &.graphiql-button-success {
-    background-color: hsla(var(--color-success), var(--alpha-background-heavy));
+    background-color: oklch(var(--accent-green));
+    border-color: oklch(var(--accent-green));
+    color: #000;
   }
   &.graphiql-button-error {
-    background-color: hsla(var(--color-error), var(--alpha-background-heavy));
+    background-color: oklch(var(--accent-red));
+    border-color: oklch(var(--accent-red));
+    color: #000;
   }
 }
diff --git a/packages/graphiql-react/src/components/button/index.tsx b/packages/graphiql-react/src/components/button/index.tsx
index b5d94fab7f8..6ea212bc22e 100644
--- a/packages/graphiql-react/src/components/button/index.tsx
+++ b/packages/graphiql-react/src/components/button/index.tsx
@@ -1,5 +1,5 @@
 import { ComponentPropsWithoutRef, forwardRef } from 'react';
-import { cn } from '../../utility';
+import { clsx as cn } from 'clsx';
 import './index.css';
 
 type UnStyledButtonProps = ComponentPropsWithoutRef<'button'>;
@@ -18,6 +18,7 @@ UnStyledButton.displayName = 'UnStyledButton';
 
 interface ButtonProps extends UnStyledButtonProps {
   state?: 'success' | 'error';
+  variant?: 'default' | 'primary';
 }
 
 export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
@@ -27,6 +28,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       ref={ref}
       className={cn(
         'graphiql-button',
+        props.variant === 'primary' && 'graphiql-button-primary',
         {
           success: 'graphiql-button-success',
           error: 'graphiql-button-error',
diff --git a/packages/graphiql-react/src/components/execute-button/index.css b/packages/graphiql-react/src/components/execute-button/index.css
index 3c7cfa3c34d..637091a8543 100644
--- a/packages/graphiql-react/src/components/execute-button/index.css
+++ b/packages/graphiql-react/src/components/execute-button/index.css
@@ -1,26 +1,28 @@
 button.graphiql-execute-button {
-  background-color: hsl(var(--color-primary));
-  border: none;
-  border-radius: var(--border-radius-8);
+  background-color: oklch(var(--btn-primary));
+  border: 1px solid oklch(var(--btn-primary-border));
+  border-radius: var(--radius-md);
   cursor: pointer;
   height: var(--toolbar-width);
   padding: 0;
   width: var(--toolbar-width);
 
   &:hover {
-    background-color: hsla(var(--color-primary), 0.9);
+    background-color: oklch(var(--btn-primary-border));
   }
 
   &:active {
-    background-color: hsla(var(--color-primary), 0.8);
+    background-color: oklch(var(--btn-primary));
+    opacity: 0.85;
   }
 
-  &:focus {
-    outline: hsla(var(--color-primary), 0.8) auto 1px;
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: 1px;
   }
 
   & > svg {
-    color: white;
+    color: #fff;
     display: block;
     height: var(--px-16);
     margin: auto;
diff --git a/packages/graphiql-react/src/components/toolbar-button/index.css b/packages/graphiql-react/src/components/toolbar-button/index.css
index 6d66de96012..5d78364f3ab 100644
--- a/packages/graphiql-react/src/components/toolbar-button/index.css
+++ b/packages/graphiql-react/src/components/toolbar-button/index.css
@@ -4,8 +4,21 @@ button.graphiql-toolbar-button {
   justify-content: center;
   height: var(--toolbar-width);
   width: var(--toolbar-width);
+  color: oklch(var(--fg-subtle));
+  border-radius: var(--radius-sm);
+
+  &:hover {
+    background-color: oklch(var(--bg-overlay));
+    color: oklch(var(--fg-default));
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: 1px;
+  }
 
   &.error {
-    background: hsla(var(--color-error), var(--alpha-background-heavy));
+    background-color: oklch(var(--accent-red) / 0.15);
+    color: oklch(var(--accent-red));
   }
 }
diff --git a/packages/graphiql-react/src/components/toolbar-button/index.tsx b/packages/graphiql-react/src/components/toolbar-button/index.tsx
index 0238d256627..55ac7e85aa2 100644
--- a/packages/graphiql-react/src/components/toolbar-button/index.tsx
+++ b/packages/graphiql-react/src/components/toolbar-button/index.tsx
@@ -4,7 +4,7 @@ import {
   useState,
   ComponentPropsWithoutRef,
 } from 'react';
-import { cn } from '../../utility';
+import { clsx as cn } from 'clsx';
 import { Tooltip } from '../tooltip';
 import { UnStyledButton } from '../button';
 import './index.css';
diff --git a/packages/graphiql-react/src/components/toolbar-button/toolbar-button.stories.tsx b/packages/graphiql-react/src/components/toolbar-button/toolbar-button.stories.tsx
new file mode 100644
index 00000000000..40c334eff70
--- /dev/null
+++ b/packages/graphiql-react/src/components/toolbar-button/toolbar-button.stories.tsx
@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as T from '@radix-ui/react-tooltip';
+import { ToolbarButton } from './';
+
+const meta: Meta<typeof ToolbarButton> = {
+  title: 'Primitives/ToolbarButton',
+  component: ToolbarButton,
+  tags: ['autodocs'],
+  args: {
+    label: 'Prettify query',
+    children: '✦',
+  },
+  decorators: [
+    Story => (
+      <T.Provider>
+        <Story />
+      </T.Provider>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ToolbarButton>;
+
+export const Default: Story = {};
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index a06ed5fcbbd..97a756ffef8 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -32,6 +32,7 @@ arthurgeron
 asiandrummer
 astro
 astrojs
+autodocs
 aumy
 Autopurge
 behaviour

From d4f026853b89b9755f28d8f4059fcba419aa6d5a Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 14 May 2026 23:12:09 -0700
Subject: [PATCH 09/38] v6: Add `KeycapHint` primitive (#4277)

## Summary

- New primitive `KeycapHint` for inline keyboard-shortcut chips.
- Renders an array of keys as `<kbd>` elements with the v6 keycap
visual.
- Required `ariaLabel` ensures every shortcut chip has a
screen-reader-readable description.
- Storybook stories for single, chord-with-modifier, and Run-shortcut
variants.
- Adds `@testing-library/react` + `@testing-library/jest-dom` as
devDeps; these are the first component unit tests in `@graphiql/react`.

## Test plan

- [ ] Open Storybook `Primitives/KeycapHint`. Each variant renders with
the v6 chip style.
- [ ] Inspect the `aria-label` on each story root; screen-reader
spot-check is optional.

Refs: graphql/graphiql#4219
---
 .changeset/keycap-hint.md                     |  5 ++++
 packages/graphiql-react/package.json          |  2 ++
 packages/graphiql-react/setup-files.ts        |  8 +++---
 .../graphiql-react/src/components/index.ts    |  2 ++
 .../src/components/keycap-hint/index.css      | 22 +++++++++++++++
 .../src/components/keycap-hint/index.tsx      | 17 ++++++++++++
 .../keycap-hint/keycap-hint.stories.tsx       | 25 +++++++++++++++++
 .../keycap-hint/keycap-hint.test.tsx          | 27 +++++++++++++++++++
 resources/custom-words.txt                    |  1 +
 yarn.lock                                     |  2 ++
 10 files changed, 108 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/keycap-hint.md
 create mode 100644 packages/graphiql-react/src/components/keycap-hint/index.css
 create mode 100644 packages/graphiql-react/src/components/keycap-hint/index.tsx
 create mode 100644 packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx

diff --git a/.changeset/keycap-hint.md b/.changeset/keycap-hint.md
new file mode 100644
index 00000000000..ddd595ec132
--- /dev/null
+++ b/.changeset/keycap-hint.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `KeycapHint` primitive for displaying inline keyboard shortcuts (e.g. `⌘K`, `⌘⏎`). Used in the new top bar; available for general consumer use.
diff --git a/packages/graphiql-react/package.json b/packages/graphiql-react/package.json
index 8b2046f044e..996717b4de4 100644
--- a/packages/graphiql-react/package.json
+++ b/packages/graphiql-react/package.json
@@ -75,6 +75,8 @@
     "@storybook/addon-a11y": "^10.3.6",
     "@storybook/addon-vitest": "^10.3.6",
     "@storybook/react-vite": "^10.3.6",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
     "@types/get-value": "^3.0.5",
     "@types/markdown-it": "^14.1.2",
     "@types/react-dom": "^19.1.2",
diff --git a/packages/graphiql-react/setup-files.ts b/packages/graphiql-react/setup-files.ts
index 984dec5f9af..c40d88eff47 100644
--- a/packages/graphiql-react/setup-files.ts
+++ b/packages/graphiql-react/setup-files.ts
@@ -1,6 +1,8 @@
-import { vi } from 'vitest';
+import { vi, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+
+afterEach(cleanup);
 
 // to make it works like Jest (auto-mocking)
 vi.mock('monaco-editor');
-
-export {};
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index eac918748b0..2aa4a0a36c6 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -18,3 +18,5 @@ export { Spinner } from './spinner';
 export { Tabs, Tab } from './tabs';
 export { Tooltip } from './tooltip';
 export { Root as VisuallyHidden } from '@radix-ui/react-visually-hidden';
+export { KeycapHint } from './keycap-hint';
+export type { KeycapHintProps } from './keycap-hint';
diff --git a/packages/graphiql-react/src/components/keycap-hint/index.css b/packages/graphiql-react/src/components/keycap-hint/index.css
new file mode 100644
index 00000000000..a756c40dfff
--- /dev/null
+++ b/packages/graphiql-react/src/components/keycap-hint/index.css
@@ -0,0 +1,22 @@
+.graphiql-keycap-hint {
+  display: inline-flex;
+  gap: var(--px-4);
+  align-items: center;
+}
+
+.graphiql-keycap {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 var(--px-4);
+  border: 1px solid oklch(var(--border-strong));
+  border-radius: var(--radius-sm);
+  background: oklch(var(--bg-canvas));
+  color: oklch(var(--fg-muted));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-eyebrow);
+  font-weight: 600;
+  line-height: 1;
+}
diff --git a/packages/graphiql-react/src/components/keycap-hint/index.tsx b/packages/graphiql-react/src/components/keycap-hint/index.tsx
new file mode 100644
index 00000000000..70c8916751e
--- /dev/null
+++ b/packages/graphiql-react/src/components/keycap-hint/index.tsx
@@ -0,0 +1,17 @@
+import type { FC } from 'react';
+import './index.css';
+
+export type KeycapHintProps = {
+  keys: string[];
+  ariaLabel: string;
+};
+
+export const KeycapHint: FC<KeycapHintProps> = ({ keys, ariaLabel }) => (
+  <span className="graphiql-keycap-hint" aria-label={ariaLabel}>
+    {keys.map((k, i) => (
+      <kbd key={`${k}-${i}`} className="graphiql-keycap">
+        {k}
+      </kbd>
+    ))}
+  </span>
+);
diff --git a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
new file mode 100644
index 00000000000..9e8baa3e93b
--- /dev/null
+++ b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
@@ -0,0 +1,25 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { KeycapHint } from './';
+
+const meta: Meta<typeof KeycapHint> = {
+  title: 'Primitives/KeycapHint',
+  component: KeycapHint,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof KeycapHint>;
+
+export const Single: Story = {
+  render: () => <KeycapHint keys={['K']} ariaLabel="Focus shortcut: K" />,
+};
+
+export const ChordWithModifier: Story = {
+  render: () => (
+    <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />
+  ),
+};
+
+export const RunShortcut: Story = {
+  render: () => <KeycapHint keys={['⌘', '⏎']} ariaLabel="Run query" />,
+};
diff --git a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx
new file mode 100644
index 00000000000..f502c8c2446
--- /dev/null
+++ b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx
@@ -0,0 +1,27 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { KeycapHint } from './';
+
+describe('KeycapHint', () => {
+  it('renders the provided keys', () => {
+    render(<KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />);
+    expect(screen.getByText('⌘')).toBeInTheDocument();
+    expect(screen.getByText('K')).toBeInTheDocument();
+  });
+
+  it('exposes the shortcut as an accessible name', () => {
+    render(
+      <KeycapHint keys={['⌘', 'Enter']} ariaLabel="Run query (Cmd+Enter)" />,
+    );
+    expect(screen.getByLabelText(/Run query/i)).toBeInTheDocument();
+  });
+
+  it('renders a <kbd> element for each key', () => {
+    const { container } = render(
+      <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />,
+    );
+    expect(container.querySelectorAll('kbd')).toHaveLength(2);
+  });
+});
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index 97a756ffef8..e5f0ff5d4b6 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -113,6 +113,7 @@ jiti
 jonathanawesome
 jsdelivr
 jsgl
+keycap
 kumar
 languageservice
 leebyron
diff --git a/yarn.lock b/yarn.lock
index 0fe13ea2029..ee4c01a5d4f 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3329,6 +3329,8 @@ __metadata:
     "@storybook/addon-a11y": "npm:^10.3.6"
     "@storybook/addon-vitest": "npm:^10.3.6"
     "@storybook/react-vite": "npm:^10.3.6"
+    "@testing-library/jest-dom": "npm:^6.6.3"
+    "@testing-library/react": "npm:^16.3.0"
     "@types/get-value": "npm:^3.0.5"
     "@types/markdown-it": "npm:^14.1.2"
     "@types/react-dom": "npm:^19.1.2"

From 34695e832ddcbb23c80a6060fe28cf0127d1d61a Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 14 May 2026 23:12:51 -0700
Subject: [PATCH 10/38] v6: Restyle `Tooltip` (#4278)

## Summary

- Migrate `Tooltip` CSS to v6 OKLCH tokens (`--bg-elevated`,
`--border-default`, `--fg-default`).
- Add `--shadow-popover` to `tokens.css` (dark + light variants) and use
it in `Tooltip`. Future Dialog and DropdownMenu PRs reuse this token.
- Pin tooltip `font-size` to `--font-size-small` (11px) rather than
`inherit`: tooltips are floating UI primitives and should render at a
consistent size regardless of where they're anchored.
- Add Storybook stories: `Primitives/Tooltip` (Default + TopPlacement).

## Test plan

- [x] Open Storybook `Primitives/Tooltip` and verify both Default and
TopPlacement render correctly.
- [x] Toggle to light theme (system preference or set
`data-theme="light"` on the Storybook root). Shadow should soften for
the lighter surface.
- [x] Hover any toolbar button in the example app. Tooltip should match
the design.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-tooltip.md                 |  5 +++
 .../src/components/tooltip/index.css          | 14 ++++----
 .../components/tooltip/tooltip.stories.tsx    | 33 +++++++++++++++++++
 packages/graphiql-react/src/style/tokens.css  | 10 ++++++
 4 files changed, 55 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/restyle-tooltip.md
 create mode 100644 packages/graphiql-react/src/components/tooltip/tooltip.stories.tsx

diff --git a/.changeset/restyle-tooltip.md b/.changeset/restyle-tooltip.md
new file mode 100644
index 00000000000..eec9ab308e0
--- /dev/null
+++ b/.changeset/restyle-tooltip.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `Tooltip` to the v6 design: `--bg-elevated` surface, simplified border and shadow.
diff --git a/packages/graphiql-react/src/components/tooltip/index.css b/packages/graphiql-react/src/components/tooltip/index.css
index 4455f9126b8..efd76acbff8 100644
--- a/packages/graphiql-react/src/components/tooltip/index.css
+++ b/packages/graphiql-react/src/components/tooltip/index.css
@@ -1,10 +1,10 @@
 .graphiql-tooltip {
-  background: hsl(var(--color-base));
-  border: var(--popover-border);
-  border-radius: var(--border-radius-4);
-  box-shadow: var(--popover-box-shadow);
-  color: hsl(var(--color-neutral));
-  font-size: inherit;
-  padding: var(--px-4) var(--px-6);
+  background: oklch(var(--bg-elevated));
+  border: 1px solid oklch(var(--border-default));
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-popover);
+  color: oklch(var(--fg-default));
   font-family: var(--font-family);
+  font-size: var(--font-size-small);
+  padding: var(--px-6) var(--px-8);
 }
diff --git a/packages/graphiql-react/src/components/tooltip/tooltip.stories.tsx b/packages/graphiql-react/src/components/tooltip/tooltip.stories.tsx
new file mode 100644
index 00000000000..2094cf7e243
--- /dev/null
+++ b/packages/graphiql-react/src/components/tooltip/tooltip.stories.tsx
@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Tooltip } from './';
+
+const meta: Meta = {
+  title: 'Primitives/Tooltip',
+  decorators: [
+    Story => (
+      <Tooltip.Provider>
+        <Story />
+      </Tooltip.Provider>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <Tooltip label="Tooltip text">
+      <button style={{ padding: '6px 12px' }}>Hover me</button>
+    </Tooltip>
+  ),
+};
+
+export const TopPlacement: Story = {
+  render: () => (
+    <Tooltip label="Appears above" side="top">
+      <button style={{ padding: '6px 12px' }}>Hover me</button>
+    </Tooltip>
+  ),
+};
diff --git a/packages/graphiql-react/src/style/tokens.css b/packages/graphiql-react/src/style/tokens.css
index 1b1a1674062..8cc2d870160 100644
--- a/packages/graphiql-react/src/style/tokens.css
+++ b/packages/graphiql-react/src/style/tokens.css
@@ -78,6 +78,10 @@
   --radius-sm: 4px;
   --radius-md: 6px;
   --radius-lg: 8px;
+
+  /* Shadows */
+  --shadow-popover:
+    0 4px 12px oklch(0% 0 0 / 0.3), 0 1px 3px oklch(0% 0 0 / 0.15);
 }
 
 [data-theme='light'] {
@@ -114,6 +118,10 @@
   --btn-primary: 51% 0.15 145;
   --btn-primary-border: 45% 0.17 145;
 
+  /* Shadows — lighter to read on light surfaces */
+  --shadow-popover:
+    0 4px 12px oklch(0% 0 0 / 0.08), 0 1px 3px oklch(0% 0 0 / 0.04);
+
   /* Typography, spacing, dimensions, and radii are inherited from :root. */
 }
 
@@ -148,5 +156,7 @@
     --accent-pink: 58% 0.22 17;
     --btn-primary: 51% 0.15 145;
     --btn-primary-border: 45% 0.17 145;
+    --shadow-popover:
+      0 4px 12px oklch(0% 0 0 / 0.08), 0 1px 3px oklch(0% 0 0 / 0.04);
   }
 }

From 1bcf3be69a883f4eda09713b0db81e738a27e310 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 07:54:08 -0700
Subject: [PATCH 11/38] v6: Restyle `Dialog` (#4279)

## Summary

- Dialog styling moves to v6 OKLCH tokens.
- Adds Storybook stories: Default and ConfirmAction. Layout matches the
real consumer pattern: title and close button in a header row, body
below.
- Bundles a Storybook decorator fix so portaled components actually
theme. Without it, `Dialog` (and any future portaled story) ignored the
toolbar's Dark / Light toggle because Radix portals render to
`document.body`, outside the wrapper div the decorator was setting
attributes on. The fix moves `data-theme` / `data-density` /
`data-font-size` to `document.documentElement` so the whole DOM
inherits.

## Test plan

- [x] Open `Primitives/Dialog` in Storybook; both stories render with
the new surface, border, and shadow. Close button sits in the header row
at top right.
- [x] Toggle the theme between Dark and Light; surface and text colors
should now actually differ (this was the symptom that prompted the
decorator fix).
- [ ] In the example app, open the Settings dialog (gear icon). Visuals
match the new look.

Refs: graphql/graphiql#4219

## Merge note

Two commits, intended for rebase-merge: dialog restyle and the storybook
decorator fix are independently reviewable.
---
 .changeset/restyle-dialog.md                  |  5 ++
 .../graphiql-react/.storybook/preview.tsx     | 26 +++---
 .../src/components/dialog/dialog.stories.tsx  | 90 +++++++++++++++++++
 .../src/components/dialog/index.css           | 14 +--
 4 files changed, 118 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/restyle-dialog.md
 create mode 100644 packages/graphiql-react/src/components/dialog/dialog.stories.tsx

diff --git a/.changeset/restyle-dialog.md b/.changeset/restyle-dialog.md
new file mode 100644
index 00000000000..76b5b641c8e
--- /dev/null
+++ b/.changeset/restyle-dialog.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `Dialog` to the v6 design: `--bg-elevated` surface, refined border, larger radius. Behavior and API unchanged.
diff --git a/packages/graphiql-react/.storybook/preview.tsx b/packages/graphiql-react/.storybook/preview.tsx
index 8004f881823..e6594dd5905 100644
--- a/packages/graphiql-react/.storybook/preview.tsx
+++ b/packages/graphiql-react/.storybook/preview.tsx
@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
 import type { Preview } from '@storybook/react-vite';
 import '../src/style/root.css';
 
@@ -48,17 +49,20 @@ const preview: Preview = {
     },
   },
   decorators: [
-    (Story, ctx) => (
-      <div
-        className="graphiql-container"
-        data-theme={ctx.globals.theme}
-        data-density={ctx.globals.density}
-        data-font-size={ctx.globals.fontSize}
-        style={{ padding: 24 }}
-      >
-        <Story />
-      </div>
-    ),
+    (Story, ctx) => {
+      useEffect(() => {
+        const root = document.documentElement;
+        root.setAttribute('data-theme', ctx.globals.theme);
+        root.setAttribute('data-density', ctx.globals.density);
+        root.setAttribute('data-font-size', ctx.globals.fontSize);
+      }, [ctx.globals.theme, ctx.globals.density, ctx.globals.fontSize]);
+
+      return (
+        <div className="graphiql-container" style={{ padding: 24 }}>
+          <Story />
+        </div>
+      );
+    },
   ],
 };
 
diff --git a/packages/graphiql-react/src/components/dialog/dialog.stories.tsx b/packages/graphiql-react/src/components/dialog/dialog.stories.tsx
new file mode 100644
index 00000000000..cbe4f929236
--- /dev/null
+++ b/packages/graphiql-react/src/components/dialog/dialog.stories.tsx
@@ -0,0 +1,90 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button';
+import { Dialog } from './';
+
+const meta: Meta = {
+  title: 'Primitives/Dialog',
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+const headerStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  padding: 'var(--px-4) var(--px-4) var(--px-4) var(--px-16)',
+  borderBottom: '1px solid oklch(var(--border-default))',
+} as const;
+
+const bodyStyle = {
+  padding: 'var(--px-16)',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 'var(--px-12)',
+} as const;
+
+export const Default: Story = {
+  render: function DefaultStory() {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Open settings</Button>
+        <Dialog open={open} onOpenChange={setOpen}>
+          <div style={{ minWidth: 360 }}>
+            <div style={headerStyle}>
+              <Dialog.Title style={{ margin: 0 }}>Settings</Dialog.Title>
+              <Dialog.Close />
+            </div>
+            <div style={bodyStyle}>
+              <Dialog.Description style={{ margin: 0 }}>
+                Update your preferences.
+              </Dialog.Description>
+            </div>
+          </div>
+        </Dialog>
+      </>
+    );
+  },
+};
+
+export const ConfirmAction: Story = {
+  render: function ConfirmActionStory() {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <Button onClick={() => setOpen(true)}>Discard changes</Button>
+        <Dialog open={open} onOpenChange={setOpen}>
+          <div style={{ minWidth: 360 }}>
+            <div style={headerStyle}>
+              <Dialog.Title style={{ margin: 0 }}>
+                Discard changes?
+              </Dialog.Title>
+              <Dialog.Close />
+            </div>
+            <div style={bodyStyle}>
+              <Dialog.Description style={{ margin: 0 }}>
+                Your unsaved changes will be lost.
+              </Dialog.Description>
+              <div
+                style={{
+                  display: 'flex',
+                  gap: 'var(--px-8)',
+                  justifyContent: 'flex-end',
+                }}
+              >
+                <Button onClick={() => setOpen(false)}>Cancel</Button>
+                <Button variant="primary" onClick={() => setOpen(false)}>
+                  Discard
+                </Button>
+              </div>
+            </div>
+          </div>
+        </Dialog>
+      </>
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/components/dialog/index.css b/packages/graphiql-react/src/components/dialog/index.css
index 256b85b4871..8f98002009f 100644
--- a/packages/graphiql-react/src/components/dialog/index.css
+++ b/packages/graphiql-react/src/components/dialog/index.css
@@ -1,7 +1,7 @@
 .graphiql-dialog-overlay {
   position: fixed;
   inset: 0;
-  background-color: hsla(var(--color-neutral), var(--alpha-background-heavy));
+  background-color: oklch(0% 0 0 / 0.5);
   /**
    * CodeMirror has a `z-index` set for the container of the scrollbar of the
    * editor, so we have to add one here to make sure that the dialog is shown
@@ -11,10 +11,12 @@
 }
 
 .graphiql-dialog {
-  background-color: hsl(var(--color-base));
-  border: var(--popover-border);
-  border-radius: var(--border-radius-12);
-  box-shadow: var(--popover-box-shadow);
+  background: oklch(var(--bg-elevated));
+  border: 1px solid oklch(var(--border-default));
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-popover);
+  color: oklch(var(--fg-default));
+  font-family: var(--font-family);
   margin: 0;
   max-height: 80vh;
   max-width: 80vw;
@@ -29,7 +31,7 @@
 }
 
 .graphiql-dialog-close > svg {
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   display: block;
   height: var(--px-12);
   padding: var(--px-12);

From 7dd211143e2e8c575363dfb8339a37c1452579dd Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 11:04:57 -0700
Subject: [PATCH 12/38] v6: Restyle `DropdownMenu` (#4280)

## Summary

- DropdownMenu styling moves to v6 OKLCH tokens (surface, item hover,
separator).
- Adds a `Separator` subcomponent wrapping the Radix primitive.
- Adds Storybook stories.

## Test plan

- [x] Open `Primitives/DropdownMenu`; check default and
separator-bearing variants.
- [x] Keyboard nav: arrow keys cycle items, Enter activates, Escape
closes.
- [x] Disabled items render with reduced contrast and don't activate.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-dropdown-menu.md           |  5 +++
 .../dropdown-menu/dropdown-menu.stories.tsx   | 40 ++++++++++++++++++
 .../src/components/dropdown-menu/index.css    | 42 ++++++++++++-------
 .../src/components/dropdown-menu/index.tsx    | 16 ++++---
 4 files changed, 83 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/restyle-dropdown-menu.md
 create mode 100644 packages/graphiql-react/src/components/dropdown-menu/dropdown-menu.stories.tsx

diff --git a/.changeset/restyle-dropdown-menu.md b/.changeset/restyle-dropdown-menu.md
new file mode 100644
index 00000000000..ad9b31e0ba4
--- /dev/null
+++ b/.changeset/restyle-dropdown-menu.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `DropdownMenu` to the v6 design. Behavior and API unchanged.
diff --git a/packages/graphiql-react/src/components/dropdown-menu/dropdown-menu.stories.tsx b/packages/graphiql-react/src/components/dropdown-menu/dropdown-menu.stories.tsx
new file mode 100644
index 00000000000..879ebd7ad9b
--- /dev/null
+++ b/packages/graphiql-react/src/components/dropdown-menu/dropdown-menu.stories.tsx
@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DropdownMenu } from './';
+
+const meta: Meta = {
+  title: 'Primitives/DropdownMenu',
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => (
+    <DropdownMenu>
+      <DropdownMenu.Button>Open menu</DropdownMenu.Button>
+      <DropdownMenu.Content>
+        <DropdownMenu.Item>Item 1</DropdownMenu.Item>
+        <DropdownMenu.Item>Item 2</DropdownMenu.Item>
+        <DropdownMenu.Separator />
+        <DropdownMenu.Item disabled>Disabled</DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  ),
+};
+
+export const WithManyItems: Story = {
+  render: () => (
+    <DropdownMenu>
+      <DropdownMenu.Button>Open menu</DropdownMenu.Button>
+      <DropdownMenu.Content>
+        <DropdownMenu.Item>Schema</DropdownMenu.Item>
+        <DropdownMenu.Item>Explorer</DropdownMenu.Item>
+        <DropdownMenu.Item>History</DropdownMenu.Item>
+        <DropdownMenu.Separator />
+        <DropdownMenu.Item>Settings</DropdownMenu.Item>
+        <DropdownMenu.Item disabled>Unavailable</DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  ),
+};
diff --git a/packages/graphiql-react/src/components/dropdown-menu/index.css b/packages/graphiql-react/src/components/dropdown-menu/index.css
index 09f4c57524e..f39ea14be2b 100644
--- a/packages/graphiql-react/src/components/dropdown-menu/index.css
+++ b/packages/graphiql-react/src/components/dropdown-menu/index.css
@@ -1,13 +1,13 @@
 .graphiql-dropdown-content {
-  background-color: hsl(var(--color-base));
-  border: var(--popover-border);
-  border-radius: var(--border-radius-8);
-  box-shadow: var(--popover-box-shadow);
-  font-size: inherit;
+  background: oklch(var(--bg-elevated));
+  border: 1px solid oklch(var(--border-default));
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-popover);
+  color: oklch(var(--fg-default));
+  font-family: var(--font-family);
+  font-size: var(--font-size-body);
   max-width: 250px;
   padding: var(--px-4);
-  font-family: var(--font-family);
-  color: hsl(var(--color-neutral));
   max-height: min(
     calc(var(--radix-dropdown-menu-content-available-height) - 10px),
     400px
@@ -16,25 +16,37 @@
 }
 
 .graphiql-dropdown-item {
-  border-radius: var(--border-radius-4);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
   font-size: inherit;
+  line-height: var(--line-height-body);
   margin: var(--px-4);
+  outline: none;
   overflow: hidden;
   padding: var(--px-6) var(--px-8);
   text-overflow: ellipsis;
   white-space: nowrap;
-  outline: none;
-  cursor: pointer;
-  line-height: var(--line-height);
 
-  &[data-selected],
-  &[data-current-nav],
+  &[data-highlighted],
   &:hover {
-    background-color: hsla(var(--color-neutral), var(--alpha-background-light));
-    color: inherit;
+    background: oklch(var(--bg-overlay));
+    color: oklch(var(--fg-strong));
+    outline: none;
+  }
+
+  &[data-disabled] {
+    color: oklch(var(--fg-disabled));
+    cursor: default;
+    pointer-events: none;
   }
 
   &:not(:first-child) {
     margin-top: 0;
   }
 }
+
+.graphiql-dropdown-separator {
+  border: none;
+  border-top: 1px solid oklch(var(--border-muted));
+  margin: var(--px-4) 0;
+}
diff --git a/packages/graphiql-react/src/components/dropdown-menu/index.tsx b/packages/graphiql-react/src/components/dropdown-menu/index.tsx
index 2aeeb243e75..8b1deab86b9 100644
--- a/packages/graphiql-react/src/components/dropdown-menu/index.tsx
+++ b/packages/graphiql-react/src/components/dropdown-menu/index.tsx
@@ -5,20 +5,18 @@ import {
   Portal,
   Content as RadixContent,
   Item as RadixItem,
+  Separator as RadixSeparator,
   DropdownMenuContentProps,
   DropdownMenuItemProps,
   Root,
 } from '@radix-ui/react-dropdown-menu';
+import { UnStyledButton } from '../button';
 import './index.css';
 
 const Button = forwardRef<HTMLButtonElement, ComponentProps<'button'>>(
   (props, ref) => (
     <Trigger asChild>
-      <button
-        {...props}
-        ref={ref}
-        className={cn('graphiql-un-styled', props.className)}
-      />
+      <UnStyledButton {...props} ref={ref} />
     </Trigger>
   ),
 );
@@ -51,8 +49,16 @@ const Item: FC<DropdownMenuItemProps> = ({ className, children, ...props }) => (
   </RadixItem>
 );
 
+const Separator: FC<ComponentProps<'div'>> = ({ className, ...props }) => (
+  <RadixSeparator
+    className={cn('graphiql-dropdown-separator', className)}
+    {...props}
+  />
+);
+
 export const DropdownMenu = Object.assign(Root, {
   Button,
   Item,
   Content,
+  Separator,
 });

From 5fb2d6487bc3e8cc3c468daf08ef56812e28b0e3 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 12:19:51 -0700
Subject: [PATCH 13/38] v6: Restyle `Tabs` (#4281)

## Summary

- Tabs primitive moves to v6 OKLCH tokens.
- Active tab uses a top accent border that overlaps the strip's bottom
border.
- Adds Storybook stories: TwoTabs and ManyTabs.

## Test plan

- [x] Open `Primitives/Tabs`; check both stories.
- [x] Arrow-key navigation cycles tabs.
- [x] Active tab's top border visually overlaps the strip's bottom
border (no double line, no gap).

Refs: graphql/graphiql#4219
---
 .changeset/restyle-tabs.md                    |  5 +
 .../graphiql-react/.storybook/preview.tsx     | 14 ++-
 .../src/components/tabs/index.css             | 77 ++++++++-------
 .../src/components/tabs/tabs.stories.tsx      | 97 +++++++++++++++++++
 4 files changed, 158 insertions(+), 35 deletions(-)
 create mode 100644 .changeset/restyle-tabs.md
 create mode 100644 packages/graphiql-react/src/components/tabs/tabs.stories.tsx

diff --git a/.changeset/restyle-tabs.md b/.changeset/restyle-tabs.md
new file mode 100644
index 00000000000..cc4f30decc4
--- /dev/null
+++ b/.changeset/restyle-tabs.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `Tabs` primitive to the v6 design. Active state uses a top accent border bleeding into the strip's bottom border.
diff --git a/packages/graphiql-react/.storybook/preview.tsx b/packages/graphiql-react/.storybook/preview.tsx
index e6594dd5905..614f0206d5f 100644
--- a/packages/graphiql-react/.storybook/preview.tsx
+++ b/packages/graphiql-react/.storybook/preview.tsx
@@ -55,10 +55,22 @@ const preview: Preview = {
         root.setAttribute('data-theme', ctx.globals.theme);
         root.setAttribute('data-density', ctx.globals.density);
         root.setAttribute('data-font-size', ctx.globals.fontSize);
+        document.body.style.background = 'oklch(var(--bg-canvas))';
+        document.body.style.color = 'oklch(var(--fg-default))';
+        document.body.style.margin = '0';
       }, [ctx.globals.theme, ctx.globals.density, ctx.globals.fontSize]);
 
       return (
-        <div className="graphiql-container" style={{ padding: 24 }}>
+        <div
+          className="graphiql-container"
+          style={{
+            padding: 24,
+            background: 'oklch(var(--bg-canvas))',
+            color: 'oklch(var(--fg-default))',
+            minHeight: '100vh',
+            boxSizing: 'border-box',
+          }}
+        >
           <Story />
         </div>
       );
diff --git a/packages/graphiql-react/src/components/tabs/index.css b/packages/graphiql-react/src/components/tabs/index.css
index f9db920622c..dd75eec0abe 100644
--- a/packages/graphiql-react/src/components/tabs/index.css
+++ b/packages/graphiql-react/src/components/tabs/index.css
@@ -1,15 +1,15 @@
+/* Tab strip container */
 .graphiql-tabs {
-  --bg: hsl(var(--color-base));
-
   display: flex;
-  align-items: center;
-  gap: var(--px-8);
+  align-items: stretch;
+  height: var(--tab-strip-height);
+  background: oklch(var(--bg-elevated));
+  border-bottom: 1px solid oklch(var(--border-default));
   /* reset browser defaults */
-  padding: 2px 0; /* Set to 2px to avoid being overflowed by focus ring */
+  padding: 0;
   margin: 0;
   list-style: none;
   overflow: auto;
-  border-top-left-radius: var(--border-radius-8);
 }
 
 /* Hide scrollbar */
@@ -22,52 +22,72 @@
   }
 }
 
-/* trick to shrink multiple tabs, instead of overflow container */
+/* trick to shrink multiple tabs instead of overflowing the container */
 .graphiql-tabs,
 .graphiql-tab {
   min-width: 0;
 }
 
 .graphiql-tab {
-  border-radius: var(--border-radius-8) var(--border-radius-8) 0 0;
-  background: hsla(var(--color-neutral), var(--alpha-background-light));
   position: relative;
   display: flex;
   flex-shrink: 0;
+  align-items: stretch;
+  border-right: 1px solid oklch(var(--border-default));
+  background: transparent;
+  color: oklch(var(--fg-subtle));
+
+  &:hover {
+    color: oklch(var(--fg-default));
 
-  /* disable shrinking while changing the operation name */
-  &:not(:focus-within) {
-    transform: none !important;
+    .graphiql-tab-close {
+      display: flex;
+    }
   }
 
-  &:hover,
-  &:focus-within,
   &.graphiql-tab-active {
-    background: var(--bg);
-    color: hsl(var(--color-neutral));
+    background: oklch(var(--bg-canvas));
+    color: oklch(var(--fg-strong));
+    /* top accent border bleeds into the strip's bottom border */
+    border-top: 1px solid oklch(var(--accent-blue));
+    margin-top: -1px;
 
     .graphiql-tab-close {
-      display: block;
+      display: flex;
     }
   }
 
   .graphiql-tab-button {
-    border-radius: var(--border-radius-12) var(--border-radius-12) 0 0;
-    padding: var(--px-4) 28px var(--px-4) var(--px-8);
+    display: flex;
+    align-items: center;
+    padding: 0 var(--px-12);
+    font-family: var(--font-family-mono);
+    font-size: var(--font-size-mono);
+    white-space: nowrap;
+    background: transparent;
+    color: inherit;
 
     &:hover {
       background: none;
     }
   }
 
+  &:hover .graphiql-tab-button,
+  &.graphiql-tab-active .graphiql-tab-button {
+    /* Reserve room for the absolutely-positioned close button. */
+    padding-right: var(--px-24);
+  }
+
   .graphiql-tab-close {
     position: absolute;
-    right: min(var(--px-4), 5%);
+    right: var(--px-4);
     top: 50%;
     transform: translateY(-50%);
     display: none;
-    background: var(--bg);
-    padding: var(--px-6);
+    align-items: center;
+    justify-content: center;
+    padding: var(--px-4);
+    color: oklch(var(--fg-muted));
     line-height: 0;
 
     & > svg {
@@ -76,18 +96,7 @@
     }
 
     &:hover {
-      background: var(--bg);
-      color: hsl(var(--color-neutral));
-      overflow: hidden; /* bg in `:before` will not overflow from radius area */
-
-      /* trick to add 2nd bg with opacity */
-      &:before {
-        content: '';
-        position: absolute;
-        inset: 0;
-        z-index: -1;
-        background: hsla(var(--color-neutral), 0.3);
-      }
+      color: oklch(var(--fg-default));
     }
   }
 }
diff --git a/packages/graphiql-react/src/components/tabs/tabs.stories.tsx b/packages/graphiql-react/src/components/tabs/tabs.stories.tsx
new file mode 100644
index 00000000000..b02614db231
--- /dev/null
+++ b/packages/graphiql-react/src/components/tabs/tabs.stories.tsx
@@ -0,0 +1,97 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Tab, Tabs } from './';
+
+const meta: Meta = {
+  title: 'Primitives/Tabs',
+  tags: ['autodocs'],
+  parameters: {
+    a11y: {
+      // The Tab primitive renders `<li role="tab">` containing a child button,
+      // which axe flags as `nested-interactive`. Fixing it cleanly means
+      // restructuring the primitive's ARIA model; that's out of scope for the
+      // restyle.
+      config: { rules: [{ id: 'nested-interactive', enabled: false }] },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const TwoTabs: Story = {
+  render: function TwoTabsStory() {
+    const [tabs] = useState([
+      { id: 'a', label: 'Query 1' },
+      { id: 'b', label: 'Query 2' },
+    ]);
+    const [active, setActive] = useState('a');
+
+    return (
+      <div style={{ fontFamily: 'var(--font-family-mono)' }}>
+        <Tabs values={tabs} onReorder={() => {}} className="no-scrollbar">
+          {tabs.map(tab => (
+            <Tab key={tab.id} value={tab} isActive={active === tab.id}>
+              <Tab.Button onClick={() => setActive(tab.id)}>
+                {tab.label}
+              </Tab.Button>
+              <Tab.Close />
+            </Tab>
+          ))}
+        </Tabs>
+        <div style={{ padding: '12px', color: 'oklch(var(--fg-default))' }}>
+          {active === 'a' ? 'First tab content' : 'Second tab content'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const ManyTabs: Story = {
+  render: function ManyTabsStory() {
+    const [tabs] = useState(
+      Array.from({ length: 6 }, (_, i) => ({
+        id: String(i),
+        label: `Operation ${i + 1}`,
+      })),
+    );
+    const [active, setActive] = useState('0');
+
+    return (
+      <div style={{ maxWidth: 360 }}>
+        <Tabs values={tabs} onReorder={() => {}} className="no-scrollbar">
+          {tabs.map(tab => (
+            <Tab key={tab.id} value={tab} isActive={active === tab.id}>
+              <Tab.Button onClick={() => setActive(tab.id)}>
+                {tab.label}
+              </Tab.Button>
+              <Tab.Close />
+            </Tab>
+          ))}
+        </Tabs>
+      </div>
+    );
+  },
+};
+
+export const ActiveState: Story = {
+  render: function ActiveStateStory() {
+    const tabs = [
+      { id: 'active', label: 'Active Tab' },
+      { id: 'inactive', label: 'Inactive' },
+    ];
+
+    return (
+      <Tabs values={tabs} onReorder={() => {}} className="no-scrollbar">
+        <Tab value={tabs[0]} isActive>
+          <Tab.Button>Active Tab</Tab.Button>
+          <Tab.Close />
+        </Tab>
+        <Tab value={tabs[1]}>
+          <Tab.Button>Inactive</Tab.Button>
+        </Tab>
+      </Tabs>
+    );
+  },
+};

From a0fe11aeb40861b586b4cfa5678b8ebe1bea4a19 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 12:24:56 -0700
Subject: [PATCH 14/38] v6: Add `SegmentedControl` primitive (#4282)

## Summary

- New primitive `SegmentedControl<T extends string>`.
- Props: `value`, `onChange`, `options`, optional `ariaLabel`. Each
option supports an icon and `disabled` flag.
- Storybook stories: ResponseView and Density.

## Test plan

- [x] Open `Primitives/SegmentedControl`; click between options to
confirm selection updates.
- [x] `aria-pressed` reflects the active option (check DOM or screen
reader).
- [x] Disabled options don't fire `onChange`.

Refs: graphql/graphiql#4219
---
 .changeset/segmented-control.md               |  5 ++
 .../graphiql-react/src/components/index.ts    |  5 ++
 .../components/segmented-control/index.css    | 42 ++++++++++
 .../components/segmented-control/index.tsx    | 47 +++++++++++
 .../segmented-control.stories.tsx             | 64 ++++++++++++++
 .../segmented-control.test.tsx                | 84 +++++++++++++++++++
 6 files changed, 247 insertions(+)
 create mode 100644 .changeset/segmented-control.md
 create mode 100644 packages/graphiql-react/src/components/segmented-control/index.css
 create mode 100644 packages/graphiql-react/src/components/segmented-control/index.tsx
 create mode 100644 packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx

diff --git a/.changeset/segmented-control.md b/.changeset/segmented-control.md
new file mode 100644
index 00000000000..ec2c3b0978c
--- /dev/null
+++ b/.changeset/segmented-control.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `SegmentedControl` primitive for selecting one option from a small set inline. Used by the new top-bar response view toggle and several settings controls.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index 2aa4a0a36c6..f93ee4efeda 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -20,3 +20,8 @@ export { Tooltip } from './tooltip';
 export { Root as VisuallyHidden } from '@radix-ui/react-visually-hidden';
 export { KeycapHint } from './keycap-hint';
 export type { KeycapHintProps } from './keycap-hint';
+export { SegmentedControl } from './segmented-control';
+export type {
+  SegmentedControlProps,
+  SegmentedControlOption,
+} from './segmented-control';
diff --git a/packages/graphiql-react/src/components/segmented-control/index.css b/packages/graphiql-react/src/components/segmented-control/index.css
new file mode 100644
index 00000000000..f30f4118417
--- /dev/null
+++ b/packages/graphiql-react/src/components/segmented-control/index.css
@@ -0,0 +1,42 @@
+.graphiql-segmented-control {
+  display: inline-flex;
+  padding: 1px;
+  background: oklch(var(--bg-subtle));
+  border: 1px solid oklch(var(--border-muted));
+  border-radius: var(--radius-md);
+  gap: 1px;
+}
+
+.graphiql-segmented-control-option {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: 3px var(--px-8);
+  border: 0;
+  background: transparent;
+  color: oklch(var(--fg-subtle));
+  border-radius: var(--radius-sm);
+  font-family: var(--font-family);
+  font-size: var(--font-size-small);
+  font-weight: 500;
+  cursor: pointer;
+  letter-spacing: var(--letter-spacing-ui);
+}
+
+.graphiql-segmented-control-option:hover:not(.active):not(:disabled) {
+  color: oklch(var(--fg-default));
+}
+
+.graphiql-segmented-control-option.active {
+  background: oklch(var(--bg-overlay));
+  color: oklch(var(--fg-strong));
+}
+
+.graphiql-segmented-control-option:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.graphiql-segmented-control-icon {
+  display: inline-flex;
+}
diff --git a/packages/graphiql-react/src/components/segmented-control/index.tsx b/packages/graphiql-react/src/components/segmented-control/index.tsx
new file mode 100644
index 00000000000..51e258132c3
--- /dev/null
+++ b/packages/graphiql-react/src/components/segmented-control/index.tsx
@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react';
+import './index.css';
+
+export type SegmentedControlOption<T extends string = string> = {
+  value: T;
+  label: ReactNode;
+  icon?: ReactNode;
+  disabled?: boolean;
+};
+
+export type SegmentedControlProps<T extends string = string> = {
+  value: T;
+  onChange: (value: T) => void;
+  options: SegmentedControlOption<T>[];
+  ariaLabel?: string;
+};
+
+export function SegmentedControl<T extends string>({
+  value,
+  onChange,
+  options,
+  ariaLabel,
+}: SegmentedControlProps<T>) {
+  return (
+    <div
+      className="graphiql-segmented-control"
+      role="group"
+      aria-label={ariaLabel}
+    >
+      {options.map(opt => (
+        <button
+          key={opt.value}
+          type="button"
+          className={`graphiql-segmented-control-option${opt.value === value ? ' active' : ''}`}
+          onClick={() => onChange(opt.value)}
+          disabled={opt.disabled}
+          aria-pressed={opt.value === value}
+        >
+          {opt.icon && (
+            <span className="graphiql-segmented-control-icon">{opt.icon}</span>
+          )}
+          <span>{opt.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx b/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
new file mode 100644
index 00000000000..13c752628d0
--- /dev/null
+++ b/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { SegmentedControl } from './';
+
+const meta: Meta = {
+  title: 'Primitives/SegmentedControl',
+  component: SegmentedControl,
+  tags: ['autodocs'],
+};
+export default meta;
+
+export const ResponseView: StoryObj = {
+  render() {
+    const [v, setV] = useState('json');
+    return (
+      <SegmentedControl
+        value={v}
+        onChange={setV}
+        ariaLabel="Response view"
+        options={[
+          { value: 'json', label: 'JSON' },
+          { value: 'tree', label: 'Tree' },
+          { value: 'table', label: 'Table' },
+        ]}
+      />
+    );
+  },
+};
+
+export const Density: StoryObj = {
+  render() {
+    const [v, setV] = useState('comfortable');
+    return (
+      <SegmentedControl
+        value={v}
+        onChange={setV}
+        ariaLabel="Density"
+        options={[
+          { value: 'compact', label: 'Compact' },
+          { value: 'comfortable', label: 'Comfortable' },
+          { value: 'spacious', label: 'Spacious' },
+        ]}
+      />
+    );
+  },
+};
+
+export const WithDisabledOption: StoryObj = {
+  render() {
+    const [v, setV] = useState('list');
+    return (
+      <SegmentedControl
+        value={v}
+        onChange={setV}
+        ariaLabel="View mode"
+        options={[
+          { value: 'list', label: 'List' },
+          { value: 'grid', label: 'Grid' },
+          { value: 'map', label: 'Map', disabled: true },
+        ]}
+      />
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx b/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx
new file mode 100644
index 00000000000..64489c1c7e7
--- /dev/null
+++ b/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx
@@ -0,0 +1,84 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState } from 'react';
+import { SegmentedControl } from './';
+
+describe('SegmentedControl', () => {
+  it('renders all options', () => {
+    render(
+      <SegmentedControl
+        value="a"
+        onChange={() => {}}
+        options={[
+          { value: 'a', label: 'Alpha' },
+          { value: 'b', label: 'Beta' },
+          { value: 'c', label: 'Gamma' },
+        ]}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Alpha' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Beta' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Gamma' })).toBeInTheDocument();
+  });
+
+  it('marks the selected option with aria-pressed', () => {
+    render(
+      <SegmentedControl
+        value="a"
+        onChange={() => {}}
+        options={[
+          { value: 'a', label: 'Alpha' },
+          { value: 'b', label: 'Beta' },
+        ]}
+      />,
+    );
+    expect(
+      screen.getByRole('button', { name: 'Alpha', pressed: true }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: 'Beta', pressed: false }),
+    ).toBeInTheDocument();
+  });
+
+  it('calls onChange when a non-selected option is clicked', async () => {
+    const user = userEvent.setup();
+    function Wrapper() {
+      const [v, setV] = useState('a');
+      return (
+        <SegmentedControl
+          value={v}
+          onChange={setV}
+          options={[
+            { value: 'a', label: 'Alpha' },
+            { value: 'b', label: 'Beta' },
+          ]}
+        />
+      );
+    }
+    render(<Wrapper />);
+    await user.click(screen.getByRole('button', { name: 'Beta' }));
+    expect(
+      screen.getByRole('button', { name: 'Beta', pressed: true }),
+    ).toBeInTheDocument();
+  });
+
+  it('does not call onChange for a disabled option', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <SegmentedControl
+        value="a"
+        onChange={onChange}
+        options={[
+          { value: 'a', label: 'Alpha' },
+          { value: 'b', label: 'Beta', disabled: true },
+        ]}
+      />,
+    );
+    await user.click(screen.getByRole('button', { name: 'Beta' }));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});

From 05ecaf0aae89a027a415f6ab070ba0be204c473a Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 12:27:33 -0700
Subject: [PATCH 15/38] v6: Restyle `Spinner` (#4283)

## Summary

Spinner stroke now uses `oklch(var(--fg-muted))`.

## Test plan

- [ ] Open the Spinner story and confirm it renders.
- [ ] Trigger a fetch in the app; verify spinner appearance.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-spinner.md                            | 5 +++++
 packages/graphiql-react/src/components/spinner/index.css | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/restyle-spinner.md

diff --git a/.changeset/restyle-spinner.md b/.changeset/restyle-spinner.md
new file mode 100644
index 00000000000..ca2c12bf27b
--- /dev/null
+++ b/.changeset/restyle-spinner.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Restyle `Spinner` to the v6 design. Default stroke uses the muted foreground token.
diff --git a/packages/graphiql-react/src/components/spinner/index.css b/packages/graphiql-react/src/components/spinner/index.css
index 43d0044b9bc..41698dfb2c3 100644
--- a/packages/graphiql-react/src/components/spinner/index.css
+++ b/packages/graphiql-react/src/components/spinner/index.css
@@ -8,7 +8,7 @@
     animation: rotation 0.8s linear 0s infinite;
     border: 4px solid transparent;
     border-radius: 100%;
-    border-top: 4px solid hsla(var(--color-neutral), var(--alpha-tertiary));
+    border-top: 4px solid oklch(var(--fg-muted));
     content: '';
     display: inline-block;
     height: 46px;

From 1ce71e407dd3b457d6fecc9e7ad0b3ad246c693b Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 20:04:45 -0700
Subject: [PATCH 16/38] v6: Add `PanelHeader` primitive (#4284)

## Summary

- New primitive `PanelHeader` for side-panel content areas.
- Props: `title` (`<h2>`), `subtitle?`, `actions?`.

## Test plan

- [x] Open `Primitives/PanelHeader` in Storybook; check TitleOnly,
WithSubtitle, and WithActions render correctly.
- [x] Confirm the title is an `<h2>` in the DOM.
- [x] Confirm action buttons are keyboard-focusable and carry their
aria-labels.

Refs: graphql/graphiql#4219
---
 .changeset/panel-header.md                    |  5 ++
 .../graphiql-react/src/components/index.ts    |  2 +
 .../src/components/panel-header/index.css     | 42 +++++++++++++++++
 .../src/components/panel-header/index.tsx     | 22 +++++++++
 .../panel-header/panel-header.stories.tsx     | 46 +++++++++++++++++++
 .../panel-header/panel-header.test.tsx        | 46 +++++++++++++++++++
 6 files changed, 163 insertions(+)
 create mode 100644 .changeset/panel-header.md
 create mode 100644 packages/graphiql-react/src/components/panel-header/index.css
 create mode 100644 packages/graphiql-react/src/components/panel-header/index.tsx
 create mode 100644 packages/graphiql-react/src/components/panel-header/panel-header.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/panel-header/panel-header.test.tsx

diff --git a/.changeset/panel-header.md b/.changeset/panel-header.md
new file mode 100644
index 00000000000..413e45b1173
--- /dev/null
+++ b/.changeset/panel-header.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `PanelHeader` primitive for side panels. Renders a title, optional subtitle, and optional action-icon row.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index f93ee4efeda..750e7295d61 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -20,6 +20,8 @@ export { Tooltip } from './tooltip';
 export { Root as VisuallyHidden } from '@radix-ui/react-visually-hidden';
 export { KeycapHint } from './keycap-hint';
 export type { KeycapHintProps } from './keycap-hint';
+export { PanelHeader } from './panel-header';
+export type { PanelHeaderProps } from './panel-header';
 export { SegmentedControl } from './segmented-control';
 export type {
   SegmentedControlProps,
diff --git a/packages/graphiql-react/src/components/panel-header/index.css b/packages/graphiql-react/src/components/panel-header/index.css
new file mode 100644
index 00000000000..f84582be71c
--- /dev/null
+++ b/packages/graphiql-react/src/components/panel-header/index.css
@@ -0,0 +1,42 @@
+.graphiql-panel-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  padding: var(--px-12) var(--px-14) var(--px-10);
+  border-bottom: 1px solid oklch(var(--border-default));
+  background: oklch(var(--bg-elevated));
+}
+
+.graphiql-panel-header-titles {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.graphiql-panel-header-title {
+  margin: 0;
+  color: oklch(var(--fg-strong));
+  font-family: var(--font-family);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.graphiql-panel-header-subtitle {
+  margin: 0;
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family);
+  font-size: var(--font-size-small);
+  line-height: var(--line-height-body);
+}
+
+.graphiql-panel-header-actions {
+  display: flex;
+  gap: var(--px-4);
+  color: oklch(var(--fg-subtle));
+}
+
+.graphiql-panel-header-actions svg {
+  width: 12px;
+  height: 12px;
+}
diff --git a/packages/graphiql-react/src/components/panel-header/index.tsx b/packages/graphiql-react/src/components/panel-header/index.tsx
new file mode 100644
index 00000000000..2241a408752
--- /dev/null
+++ b/packages/graphiql-react/src/components/panel-header/index.tsx
@@ -0,0 +1,22 @@
+import type { FC, ReactNode } from 'react';
+import './index.css';
+
+export type PanelHeaderProps = {
+  title: ReactNode;
+  subtitle?: ReactNode;
+  actions?: ReactNode;
+};
+
+export const PanelHeader: FC<PanelHeaderProps> = ({
+  title,
+  subtitle,
+  actions,
+}) => (
+  <header className="graphiql-panel-header">
+    <div className="graphiql-panel-header-titles">
+      <h2 className="graphiql-panel-header-title">{title}</h2>
+      {subtitle && <p className="graphiql-panel-header-subtitle">{subtitle}</p>}
+    </div>
+    {actions && <div className="graphiql-panel-header-actions">{actions}</div>}
+  </header>
+);
diff --git a/packages/graphiql-react/src/components/panel-header/panel-header.stories.tsx b/packages/graphiql-react/src/components/panel-header/panel-header.stories.tsx
new file mode 100644
index 00000000000..7d62b06c52b
--- /dev/null
+++ b/packages/graphiql-react/src/components/panel-header/panel-header.stories.tsx
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MagnifyingGlassIcon, SettingsIcon } from '../../icons';
+import { ToolbarButton } from '../toolbar-button';
+import { Tooltip } from '../tooltip';
+import { PanelHeader } from './';
+
+const meta: Meta<typeof PanelHeader> = {
+  title: 'Primitives/PanelHeader',
+  component: PanelHeader,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <Tooltip.Provider>
+        <Story />
+      </Tooltip.Provider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof PanelHeader>;
+
+export const TitleOnly: Story = {
+  args: { title: 'Schema' },
+};
+
+export const WithSubtitle: Story = {
+  args: { title: 'Schema', subtitle: 'Pokemon API' },
+};
+
+export const WithActions: Story = {
+  args: {
+    title: 'History',
+    subtitle: 'Last 500 runs, searchable.',
+    actions: (
+      <>
+        <ToolbarButton label="Search">
+          <MagnifyingGlassIcon aria-hidden="true" />
+        </ToolbarButton>
+        <ToolbarButton label="Settings">
+          <SettingsIcon aria-hidden="true" />
+        </ToolbarButton>
+      </>
+    ),
+  },
+};
diff --git a/packages/graphiql-react/src/components/panel-header/panel-header.test.tsx b/packages/graphiql-react/src/components/panel-header/panel-header.test.tsx
new file mode 100644
index 00000000000..9d3b6e2664a
--- /dev/null
+++ b/packages/graphiql-react/src/components/panel-header/panel-header.test.tsx
@@ -0,0 +1,46 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { PanelHeader } from './';
+
+describe('PanelHeader', () => {
+  it('renders the title', () => {
+    render(<PanelHeader title="Schema" />);
+    expect(screen.getByText('Schema')).toBeInTheDocument();
+  });
+
+  it('renders the subtitle when provided', () => {
+    render(<PanelHeader title="Schema" subtitle="Pokemon API" />);
+    expect(screen.getByText('Pokemon API')).toBeInTheDocument();
+  });
+
+  it('does not render a subtitle element when omitted', () => {
+    const { container } = render(<PanelHeader title="Schema" />);
+    expect(
+      container.querySelector('.graphiql-panel-header-subtitle'),
+    ).toBeNull();
+  });
+
+  it('renders action icons when provided', () => {
+    render(
+      <PanelHeader
+        title="Schema"
+        actions={<button aria-label="Refresh">↻</button>}
+      />,
+    );
+    expect(screen.getByLabelText('Refresh')).toBeInTheDocument();
+  });
+
+  it('does not render the actions container when omitted', () => {
+    const { container } = render(<PanelHeader title="Schema" />);
+    expect(
+      container.querySelector('.graphiql-panel-header-actions'),
+    ).toBeNull();
+  });
+
+  it('renders the title in an h2', () => {
+    const { container } = render(<PanelHeader title="History" />);
+    expect(container.querySelector('h2')).toHaveTextContent('History');
+  });
+});

From c25bfd5b51ad98f36cbdb81a7486380f8dd1ab6a Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 21:08:02 -0700
Subject: [PATCH 17/38] v6: Add `MethodPill` primitive (#4285)

## Summary

- New primitive `MethodPill` labeling operation types: QRY (green), MUT
(yellow), SUB (purple).
- Three Storybook stories covering each operation.

## Test plan

- [x] Open `Primitives/MethodPill` and confirm each variant's color and
label.
- [x] Pill renders as decorative; consumers pair it with the operation
name for the accessible name.

Refs: graphql/graphiql#4219
---
 .changeset/method-pill.md                     |  5 +++
 .../graphiql-react/src/components/index.ts    |  2 ++
 .../src/components/method-pill/index.css      | 32 +++++++++++++++++++
 .../src/components/method-pill/index.tsx      | 24 ++++++++++++++
 .../method-pill/method-pill.stories.tsx       | 23 +++++++++++++
 .../method-pill/method-pill.test.tsx          | 22 +++++++++++++
 6 files changed, 108 insertions(+)
 create mode 100644 .changeset/method-pill.md
 create mode 100644 packages/graphiql-react/src/components/method-pill/index.css
 create mode 100644 packages/graphiql-react/src/components/method-pill/index.tsx
 create mode 100644 packages/graphiql-react/src/components/method-pill/method-pill.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/method-pill/method-pill.test.tsx

diff --git a/.changeset/method-pill.md b/.changeset/method-pill.md
new file mode 100644
index 00000000000..e5697f77539
--- /dev/null
+++ b/.changeset/method-pill.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `MethodPill` primitive: a small colored pill labeling an operation as QRY (query), MUT (mutation), or SUB (subscription).
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index 750e7295d61..bae025879f7 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -27,3 +27,5 @@ export type {
   SegmentedControlProps,
   SegmentedControlOption,
 } from './segmented-control';
+export { MethodPill } from './method-pill';
+export type { MethodPillProps, Operation } from './method-pill';
diff --git a/packages/graphiql-react/src/components/method-pill/index.css b/packages/graphiql-react/src/components/method-pill/index.css
new file mode 100644
index 00000000000..2cc06618b9d
--- /dev/null
+++ b/packages/graphiql-react/src/components/method-pill/index.css
@@ -0,0 +1,32 @@
+.graphiql-method-pill {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1px 5px;
+  border-radius: var(--radius-sm);
+  font-family: var(--font-family-mono);
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  line-height: 1.4;
+}
+
+/*
+ * Pills use solid backgrounds rather than alpha tints so they read the
+ * same regardless of what surface they're stacked on, and contrast against
+ * the pill text stays well above WCAG AA in both themes.
+ */
+.graphiql-method-pill-query {
+  color: oklch(98% 0 0);
+  background: oklch(50% 0.15 146);
+}
+
+.graphiql-method-pill-mutation {
+  color: oklch(15% 0 0);
+  background: oklch(85% 0.13 90);
+}
+
+.graphiql-method-pill-subscription {
+  color: oklch(98% 0 0);
+  background: oklch(45% 0.18 295);
+}
diff --git a/packages/graphiql-react/src/components/method-pill/index.tsx b/packages/graphiql-react/src/components/method-pill/index.tsx
new file mode 100644
index 00000000000..49ef2ad7ae5
--- /dev/null
+++ b/packages/graphiql-react/src/components/method-pill/index.tsx
@@ -0,0 +1,24 @@
+import type { FC } from 'react';
+import './index.css';
+
+export type Operation = 'query' | 'mutation' | 'subscription';
+
+const LABELS: Record<Operation, string> = {
+  query: 'QRY',
+  mutation: 'MUT',
+  subscription: 'SUB',
+};
+
+export type MethodPillProps = {
+  operation: Operation;
+  'aria-hidden'?: boolean;
+};
+
+export const MethodPill: FC<MethodPillProps> = ({ operation, ...rest }) => (
+  <span
+    className={`graphiql-method-pill graphiql-method-pill-${operation}`}
+    {...rest}
+  >
+    {LABELS[operation]}
+  </span>
+);
diff --git a/packages/graphiql-react/src/components/method-pill/method-pill.stories.tsx b/packages/graphiql-react/src/components/method-pill/method-pill.stories.tsx
new file mode 100644
index 00000000000..e908ff4ce21
--- /dev/null
+++ b/packages/graphiql-react/src/components/method-pill/method-pill.stories.tsx
@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { MethodPill } from './';
+
+const meta: Meta<typeof MethodPill> = {
+  title: 'Primitives/MethodPill',
+  component: MethodPill,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof MethodPill>;
+
+export const Query: Story = {
+  render: () => <MethodPill operation="query" />,
+};
+
+export const Mutation: Story = {
+  render: () => <MethodPill operation="mutation" />,
+};
+
+export const Subscription: Story = {
+  render: () => <MethodPill operation="subscription" />,
+};
diff --git a/packages/graphiql-react/src/components/method-pill/method-pill.test.tsx b/packages/graphiql-react/src/components/method-pill/method-pill.test.tsx
new file mode 100644
index 00000000000..43362debd12
--- /dev/null
+++ b/packages/graphiql-react/src/components/method-pill/method-pill.test.tsx
@@ -0,0 +1,22 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { MethodPill } from './';
+
+describe('MethodPill', () => {
+  it('renders QRY for query operations', () => {
+    render(<MethodPill operation="query" />);
+    expect(screen.getByText('QRY')).toBeInTheDocument();
+  });
+
+  it('renders MUT for mutations', () => {
+    render(<MethodPill operation="mutation" />);
+    expect(screen.getByText('MUT')).toBeInTheDocument();
+  });
+
+  it('renders SUB for subscriptions', () => {
+    render(<MethodPill operation="subscription" />);
+    expect(screen.getByText('SUB')).toBeInTheDocument();
+  });
+});

From e54b9c94ab0b61d47731554362c6641a12aa0112 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 15 May 2026 21:21:20 -0700
Subject: [PATCH 18/38] v6: Rewrite `SegmentedControl` on native radio inputs
 (#4287)

## Summary

- Rewrites `SegmentedControl` to render `<fieldset>` + hidden `<input
type="radio">` per option, with a visible `<label>` doing the visual
work. Public props (`value`, `onChange`, `options`, `ariaLabel`) stay
the same.
- Browser handles ArrowLeft / Right / Up / Down / Home / End across the
group, and the whole control is a single tab stop.
- Adds an `Icons` story using real icons from `~/icons`;
`options[].icon` was always supported but had no demo.

## Test plan

- [x] Open `Primitives/SegmentedControl`; tab into the group, press
ArrowRight, watch selection move across options.
- [x] Try the `WithDisabledOption` story; arrow nav skips the disabled
option.
- [x] Screen-reader spot-check: the group announces as `radiogroup` with
the provided label; each option announces its checked state.

Refs: graphql/graphiql#4219
---
 .changeset/segmented-control-radio.md         |  5 +++
 .../components/segmented-control/index.css    | 42 +++++++++++++----
 .../components/segmented-control/index.tsx    | 39 ++++++++++------
 .../segmented-control.stories.tsx             | 31 +++++++++++++
 .../segmented-control.test.tsx                | 45 ++++++++++++-------
 5 files changed, 125 insertions(+), 37 deletions(-)
 create mode 100644 .changeset/segmented-control-radio.md

diff --git a/.changeset/segmented-control-radio.md b/.changeset/segmented-control-radio.md
new file mode 100644
index 00000000000..20dbbc001d9
--- /dev/null
+++ b/.changeset/segmented-control-radio.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+Rewrite `SegmentedControl` on top of native radio inputs. Public props are unchanged. Keyboard navigation (arrow keys, Home / End) and screen-reader semantics now come from the browser; the group is a single tab stop instead of one per option.
diff --git a/packages/graphiql-react/src/components/segmented-control/index.css b/packages/graphiql-react/src/components/segmented-control/index.css
index f30f4118417..2c483fc3f55 100644
--- a/packages/graphiql-react/src/components/segmented-control/index.css
+++ b/packages/graphiql-react/src/components/segmented-control/index.css
@@ -1,42 +1,68 @@
 .graphiql-segmented-control {
   display: inline-flex;
   padding: 1px;
-  background: oklch(var(--bg-subtle));
+  margin: 0;
   border: 1px solid oklch(var(--border-muted));
   border-radius: var(--radius-md);
+  background: oklch(var(--bg-subtle));
   gap: 1px;
 }
 
+.graphiql-segmented-control-legend {
+  position: absolute;
+  clip-path: inset(50%);
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  opacity: 0;
+}
+
+.graphiql-segmented-control-input {
+  position: absolute;
+  clip-path: inset(50%);
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  opacity: 0;
+}
+
 .graphiql-segmented-control-option {
   display: inline-flex;
   align-items: center;
   gap: var(--px-6);
   padding: 3px var(--px-8);
-  border: 0;
-  background: transparent;
-  color: oklch(var(--fg-subtle));
   border-radius: var(--radius-sm);
+  color: oklch(var(--fg-subtle));
   font-family: var(--font-family);
   font-size: var(--font-size-small);
   font-weight: 500;
-  cursor: pointer;
   letter-spacing: var(--letter-spacing-ui);
+  cursor: pointer;
 }
 
-.graphiql-segmented-control-option:hover:not(.active):not(:disabled) {
+.graphiql-segmented-control-option:hover:not([data-checked]):not(
+    [data-disabled]
+  ) {
   color: oklch(var(--fg-default));
 }
 
-.graphiql-segmented-control-option.active {
+.graphiql-segmented-control-option[data-checked] {
   background: oklch(var(--bg-overlay));
   color: oklch(var(--fg-strong));
 }
 
-.graphiql-segmented-control-option:disabled {
+.graphiql-segmented-control-option[data-disabled] {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
+.graphiql-segmented-control-option:has(
+  .graphiql-segmented-control-input:focus-visible
+) {
+  outline: 2px solid oklch(var(--accent-blue));
+  outline-offset: 1px;
+}
+
 .graphiql-segmented-control-icon {
   display: inline-flex;
 }
diff --git a/packages/graphiql-react/src/components/segmented-control/index.tsx b/packages/graphiql-react/src/components/segmented-control/index.tsx
index 51e258132c3..68344f3dcff 100644
--- a/packages/graphiql-react/src/components/segmented-control/index.tsx
+++ b/packages/graphiql-react/src/components/segmented-control/index.tsx
@@ -1,4 +1,6 @@
-import type { ReactNode } from 'react';
+'use no memo';
+
+import { useId, type ReactNode } from 'react';
 import './index.css';
 
 export type SegmentedControlOption<T extends string = string> = {
@@ -21,27 +23,36 @@ export function SegmentedControl<T extends string>({
   options,
   ariaLabel,
 }: SegmentedControlProps<T>) {
+  const name = useId();
   return (
-    <div
-      className="graphiql-segmented-control"
-      role="group"
-      aria-label={ariaLabel}
-    >
+    <fieldset className="graphiql-segmented-control">
+      {ariaLabel && (
+        <legend className="graphiql-segmented-control-legend">
+          {ariaLabel}
+        </legend>
+      )}
       {options.map(opt => (
-        <button
+        <label
           key={opt.value}
-          type="button"
-          className={`graphiql-segmented-control-option${opt.value === value ? ' active' : ''}`}
-          onClick={() => onChange(opt.value)}
-          disabled={opt.disabled}
-          aria-pressed={opt.value === value}
+          className="graphiql-segmented-control-option"
+          data-checked={opt.value === value || undefined}
+          data-disabled={opt.disabled || undefined}
         >
+          <input
+            className="graphiql-segmented-control-input"
+            type="radio"
+            name={name}
+            value={opt.value}
+            checked={opt.value === value}
+            disabled={opt.disabled}
+            onChange={() => onChange(opt.value)}
+          />
           {opt.icon && (
             <span className="graphiql-segmented-control-icon">{opt.icon}</span>
           )}
           <span>{opt.label}</span>
-        </button>
+        </label>
       ))}
-    </div>
+    </fieldset>
   );
 }
diff --git a/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx b/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
index 13c752628d0..2f6d3843b0a 100644
--- a/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
+++ b/packages/graphiql-react/src/components/segmented-control/segmented-control.stories.tsx
@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
 import { SegmentedControl } from './';
+import { PrettifyIcon, DocsIcon, MergeIcon } from '../../icons';
 
 const meta: Meta = {
   title: 'Primitives/SegmentedControl',
@@ -62,3 +63,33 @@ export const WithDisabledOption: StoryObj = {
     );
   },
 };
+
+export const Icons: StoryObj = {
+  render() {
+    const [v, setV] = useState('pretty');
+    return (
+      <SegmentedControl
+        value={v}
+        onChange={setV}
+        ariaLabel="Response view"
+        options={[
+          {
+            value: 'pretty',
+            label: 'Pretty',
+            icon: <PrettifyIcon aria-hidden="true" />,
+          },
+          {
+            value: 'docs',
+            label: 'Docs',
+            icon: <DocsIcon aria-hidden="true" />,
+          },
+          {
+            value: 'merged',
+            label: 'Merged',
+            icon: <MergeIcon aria-hidden="true" />,
+          },
+        ]}
+      />
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx b/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx
index 64489c1c7e7..f868b644ebf 100644
--- a/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx
+++ b/packages/graphiql-react/src/components/segmented-control/segmented-control.test.tsx
@@ -19,12 +19,12 @@ describe('SegmentedControl', () => {
         ]}
       />,
     );
-    expect(screen.getByRole('button', { name: 'Alpha' })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: 'Beta' })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: 'Gamma' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Alpha' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Beta' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Gamma' })).toBeInTheDocument();
   });
 
-  it('marks the selected option with aria-pressed', () => {
+  it('marks the selected option as checked', () => {
     render(
       <SegmentedControl
         value="a"
@@ -35,12 +35,8 @@ describe('SegmentedControl', () => {
         ]}
       />,
     );
-    expect(
-      screen.getByRole('button', { name: 'Alpha', pressed: true }),
-    ).toBeInTheDocument();
-    expect(
-      screen.getByRole('button', { name: 'Beta', pressed: false }),
-    ).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Alpha' })).toBeChecked();
+    expect(screen.getByRole('radio', { name: 'Beta' })).not.toBeChecked();
   });
 
   it('calls onChange when a non-selected option is clicked', async () => {
@@ -59,10 +55,8 @@ describe('SegmentedControl', () => {
       );
     }
     render(<Wrapper />);
-    await user.click(screen.getByRole('button', { name: 'Beta' }));
-    expect(
-      screen.getByRole('button', { name: 'Beta', pressed: true }),
-    ).toBeInTheDocument();
+    await user.click(screen.getByRole('radio', { name: 'Beta' }));
+    expect(screen.getByRole('radio', { name: 'Beta' })).toBeChecked();
   });
 
   it('does not call onChange for a disabled option', async () => {
@@ -78,7 +72,28 @@ describe('SegmentedControl', () => {
         ]}
       />,
     );
-    await user.click(screen.getByRole('button', { name: 'Beta' }));
+    await user.click(screen.getByRole('radio', { name: 'Beta' }));
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it('moves selection with ArrowRight keyboard navigation', async () => {
+    const user = userEvent.setup();
+    function Wrapper() {
+      const [v, setV] = useState('a');
+      return (
+        <SegmentedControl
+          value={v}
+          onChange={setV}
+          options={[
+            { value: 'a', label: 'Alpha' },
+            { value: 'b', label: 'Beta' },
+          ]}
+        />
+      );
+    }
+    render(<Wrapper />);
+    screen.getByRole('radio', { name: 'Alpha' }).focus();
+    await user.keyboard('{ArrowRight}');
+    expect(screen.getByRole('radio', { name: 'Beta' })).toBeChecked();
+  });
 });

From 66276352a63da0a6c9924fcd488296d08e6f3a1b Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 10:50:36 -0700
Subject: [PATCH 19/38] v6: Mirror the active theme to `data-theme` on `<html>`
 (#4293)

## Summary

`tokens.css` scopes the v6 OKLCH cascade to `[data-theme='light']` /
`[data-theme='dark']` selectors, but `setTheme` was only writing
`graphiql-light` / `graphiql-dark` classes onto `<body>`. With no
`data-theme` attribute set, v6 components fell through to the OS
`prefers-color-scheme` media-query fallback regardless of the in-app
toggle. This PR mirrors the active theme onto `document.documentElement`
as `data-theme` so the selectors actually match; the existing body
classes are preserved for any consumer CSS that depends on them.

## Test plan

- [ ] Open the [deploy
preview](https://deploy-preview-4293--graphiql-test.netlify.app). With
the GraphiQL theme dropdown set to System, confirm `<html>` has no
`data-theme` attribute and v6 chrome follows your OS preference.
- [ ] Toggle the theme to Light; confirm `<html>` gains
`data-theme="light"` and v6 components (`TopBar`, `StatusBar`,
`ActivityRail`, etc., once those PRs land) all switch to light tokens.
- [ ] Toggle the theme to Dark; confirm `<html>` gains
`data-theme="dark"` and v6 components switch to dark tokens.
- [ ] Toggle back to System; confirm `data-theme` is removed and the v6
components revert to following the OS preference.

Refs: graphql/graphiql#4219
---
 .changeset/theme-data-attribute.md          | 5 +++++
 packages/graphiql-react/src/stores/theme.ts | 3 +++
 2 files changed, 8 insertions(+)
 create mode 100644 .changeset/theme-data-attribute.md

diff --git a/.changeset/theme-data-attribute.md b/.changeset/theme-data-attribute.md
new file mode 100644
index 00000000000..50b590de76a
--- /dev/null
+++ b/.changeset/theme-data-attribute.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': patch
+---
+
+`setTheme` now mirrors the chosen theme onto `document.documentElement` as a `data-theme` attribute. The v6 OKLCH token cascade in `tokens.css` is gated on `[data-theme='light']` / `[data-theme='dark']` selectors and was previously never matched, so v6 components fell back to the OS `prefers-color-scheme` regardless of the GraphiQL theme toggle. The existing `body.graphiql-light` / `body.graphiql-dark` classes are preserved for backwards compatibility with custom CSS.
diff --git a/packages/graphiql-react/src/stores/theme.ts b/packages/graphiql-react/src/stores/theme.ts
index 4ed14ce8ec2..ac2cb7c3405 100644
--- a/packages/graphiql-react/src/stores/theme.ts
+++ b/packages/graphiql-react/src/stores/theme.ts
@@ -60,6 +60,9 @@ export const createThemeSlice: CreateThemeSlice =
         document.body.classList.remove('graphiql-light', 'graphiql-dark');
         if (theme) {
           document.body.classList.add(`graphiql-${theme}`);
+          document.documentElement.setAttribute('data-theme', theme);
+        } else {
+          document.documentElement.removeAttribute('data-theme');
         }
         const { monaco } = monacoStore.getState();
         const resolvedTheme = theme ?? getSystemTheme();

From 82e54602731305d955da5dbf911073f9430fac99 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 11:09:03 -0700
Subject: [PATCH 20/38] v6: Add `TopBar` layout component (#4288)

## Summary

This PR introduces the top bar that anchors the new GraphiQL v6 layout.
It renders the brand, an endpoint URL display, a command palette button,
and a primary Run button across the top of the app. The endpoint URL and
command palette are intentional placeholders; their behavior will fill
in once the transport and command palette work land.

## Test plan

- [x] Open the [deploy
preview](https://deploy-preview-4288--graphiql-test.netlify.app).
Confirm the top bar spans the full width above the editor/sidebar split,
showing the brand, endpoint URL placeholder, command palette button, and
Run button.
- [x] In the deploy preview, type a query and click Run. Confirm the
button disables for the duration of the fetch and re-enables once
results arrive.
- [x] In the deploy preview, open the settings dialog and toggle
dark/light theme. Confirm the top bar reads from the active tokens in
both modes.
- [x] Tab through the bar with the keyboard. Confirm the Run button is
reachable and activates with Space or Enter.

Refs: graphql/graphiql#4219
---
 .changeset/topbar-component.md                |   6 +
 .../graphiql-react/src/components/index.ts    |   2 +
 .../src/components/top-bar/index.css          | 122 ++++++++++++++
 .../src/components/top-bar/index.tsx          |  78 +++++++++
 .../components/top-bar/top-bar.stories.tsx    |  38 +++++
 .../src/components/top-bar/top-bar.test.tsx   |  75 +++++++++
 packages/graphiql/src/GraphiQL.spec.tsx       |   4 +-
 packages/graphiql/src/GraphiQL.tsx            | 150 +++++++++---------
 packages/graphiql/src/graphiql.css            |   9 ++
 resources/custom-words.txt                    |   1 +
 10 files changed, 410 insertions(+), 75 deletions(-)
 create mode 100644 .changeset/topbar-component.md
 create mode 100644 packages/graphiql-react/src/components/top-bar/index.css
 create mode 100644 packages/graphiql-react/src/components/top-bar/index.tsx
 create mode 100644 packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/top-bar/top-bar.test.tsx

diff --git a/.changeset/topbar-component.md b/.changeset/topbar-component.md
new file mode 100644
index 00000000000..000dbd8b61d
--- /dev/null
+++ b/.changeset/topbar-component.md
@@ -0,0 +1,6 @@
+---
+'@graphiql/react': minor
+'graphiql': patch
+---
+
+Add a new `TopBar` layout component with brand, endpoint URL display, command palette button, and primary Run button. Endpoint method/URL are placeholders until the transport API lands. `TopBar` is now mounted at the top of the GraphiQL layout.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index bae025879f7..d3e9ce0937d 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -29,3 +29,5 @@ export type {
 } from './segmented-control';
 export { MethodPill } from './method-pill';
 export type { MethodPillProps, Operation } from './method-pill';
+export { TopBar, TopBarView } from './top-bar';
+export type { TopBarProps, TopBarViewProps } from './top-bar';
diff --git a/packages/graphiql-react/src/components/top-bar/index.css b/packages/graphiql-react/src/components/top-bar/index.css
new file mode 100644
index 00000000000..85b1dfec25a
--- /dev/null
+++ b/packages/graphiql-react/src/components/top-bar/index.css
@@ -0,0 +1,122 @@
+.graphiql-top-bar {
+  display: flex;
+  align-items: center;
+  gap: var(--px-12);
+  height: var(--top-bar-height);
+  padding: 0 var(--px-12);
+  background: oklch(var(--bg-elevated));
+  border-bottom: 1px solid oklch(var(--border-default));
+  color: oklch(var(--fg-default));
+  font-family: var(--font-family);
+  font-size: var(--font-size-body);
+}
+
+.graphiql-top-bar-brand {
+  display: flex;
+  align-items: center;
+  gap: var(--px-8);
+}
+
+.graphiql-top-bar-logo {
+  width: 22px;
+  height: 22px;
+  border-radius: var(--radius-md);
+  background: linear-gradient(
+    135deg,
+    oklch(var(--accent-green-light)),
+    oklch(var(--accent-blue))
+  );
+  flex-shrink: 0;
+}
+
+.graphiql-top-bar-wordmark {
+  color: oklch(var(--fg-strong));
+  font-weight: 600;
+  font-size: var(--font-size-body);
+  white-space: nowrap;
+}
+
+.graphiql-top-bar-version {
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-small);
+  white-space: nowrap;
+}
+
+.graphiql-top-bar-divider {
+  width: 1px;
+  height: 18px;
+  background: oklch(var(--border-default));
+  flex-shrink: 0;
+}
+
+.graphiql-top-bar-cmd {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: 0 var(--px-10);
+  height: 24px;
+  background: oklch(var(--bg-subtle));
+  border: 1px solid oklch(var(--border-strong));
+  border-radius: var(--radius-md);
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-small);
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.graphiql-top-bar-endpoint {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: 0 var(--px-10);
+  height: 24px;
+  flex: 1;
+  min-width: 0;
+  background: oklch(var(--bg-canvas));
+  border: 1px solid oklch(var(--border-muted));
+  border-radius: var(--radius-md);
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-small);
+}
+
+.graphiql-top-bar-endpoint-method {
+  color: oklch(var(--accent-green));
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+.graphiql-top-bar-endpoint-url {
+  color: oklch(var(--fg-subtle));
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.graphiql-top-bar-run {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-8);
+  padding: 0 var(--px-10);
+  height: 28px;
+  background: oklch(var(--btn-primary));
+  border: 1px solid oklch(var(--btn-primary-border));
+  border-radius: var(--radius-md);
+  color: #fff;
+  font-family: var(--font-family);
+  font-size: var(--font-size-body);
+  font-weight: 600;
+  cursor: pointer;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.graphiql-top-bar-run:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.graphiql-top-bar-run:not(:disabled):hover {
+  filter: brightness(1.1);
+}
diff --git a/packages/graphiql-react/src/components/top-bar/index.tsx b/packages/graphiql-react/src/components/top-bar/index.tsx
new file mode 100644
index 00000000000..20f7c9ab619
--- /dev/null
+++ b/packages/graphiql-react/src/components/top-bar/index.tsx
@@ -0,0 +1,78 @@
+// React Compiler can stale-cache the references returned by zustand hooks;
+// opt this file out so `useGraphiQL` / `useGraphiQLActions` stay live.
+'use no memo';
+
+import type { FC } from 'react';
+import { useGraphiQL, useGraphiQLActions } from '../provider';
+import { KeycapHint } from '../keycap-hint';
+import './index.css';
+
+export type TopBarProps = {
+  /** Endpoint URL to display (placeholder until transport lands). */
+  endpointUrl?: string;
+  /** Version string shown in the brand pill. */
+  version?: string;
+};
+
+export const TopBar: FC<TopBarProps> = ({ endpointUrl, version }) => {
+  const { run } = useGraphiQLActions();
+  const isFetching = useGraphiQL(state => state.isFetching);
+
+  return (
+    <TopBarView
+      endpointUrl={endpointUrl}
+      version={version}
+      isFetching={isFetching}
+      onRun={run}
+    />
+  );
+};
+
+export type TopBarViewProps = {
+  endpointUrl?: string;
+  version?: string;
+  isFetching: boolean;
+  onRun: () => void;
+};
+
+export const TopBarView: FC<TopBarViewProps> = ({
+  endpointUrl,
+  version,
+  isFetching,
+  onRun,
+}) => {
+  return (
+    <header className="graphiql-top-bar" role="banner">
+      <div className="graphiql-top-bar-brand">
+        <span className="graphiql-top-bar-logo" aria-hidden="true" />
+        <span className="graphiql-top-bar-wordmark">GraphiQL</span>
+        {version && <span className="graphiql-top-bar-version">{version}</span>}
+      </div>
+
+      <div className="graphiql-top-bar-divider" aria-hidden="true" />
+
+      <div className="graphiql-top-bar-endpoint">
+        <span className="graphiql-top-bar-endpoint-method">POST</span>
+        <span className="graphiql-top-bar-endpoint-url">
+          {endpointUrl ?? '/graphql'}
+        </span>
+      </div>
+
+      <button type="button" className="graphiql-top-bar-cmd">
+        <span>Jump to schema</span>
+        <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />
+      </button>
+
+      <button
+        type="button"
+        className="graphiql-top-bar-run"
+        onClick={onRun}
+        disabled={isFetching}
+        aria-label="Run query"
+      >
+        Run
+        <KeycapHint keys={['⌘', '⏎']} ariaLabel="Run query shortcut" />
+      </button>
+    </header>
+  );
+};
diff --git a/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx b/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
new file mode 100644
index 00000000000..15200eac08c
--- /dev/null
+++ b/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { GraphiQLProvider } from '../provider';
+import { TopBar } from './';
+
+const noOpFetcher = () => Promise.resolve({ data: {} });
+
+const meta: Meta<typeof TopBar> = {
+  title: 'Layout/TopBar',
+  component: TopBar,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <GraphiQLProvider fetcher={noOpFetcher}>
+        <Story />
+      </GraphiQLProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof TopBar>;
+
+export const Default: Story = {
+  args: {
+    endpointUrl: 'https://api.example.com/graphql',
+    version: 'v6.0.0-alpha.1',
+  },
+};
+
+export const NoVersion: Story = {
+  args: {
+    endpointUrl: '/graphql',
+  },
+};
+
+export const Minimal: Story = {
+  args: {},
+};
diff --git a/packages/graphiql-react/src/components/top-bar/top-bar.test.tsx b/packages/graphiql-react/src/components/top-bar/top-bar.test.tsx
new file mode 100644
index 00000000000..cfb858b1b41
--- /dev/null
+++ b/packages/graphiql-react/src/components/top-bar/top-bar.test.tsx
@@ -0,0 +1,75 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { TopBarView } from './';
+
+const DEFAULTS = {
+  isFetching: false,
+  onRun() {},
+};
+
+describe('TopBarView', () => {
+  it('renders the Run button', () => {
+    render(<TopBarView {...DEFAULTS} />);
+    expect(
+      screen.getByRole('button', { name: /Run query/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders the GraphiQL wordmark', () => {
+    render(<TopBarView {...DEFAULTS} />);
+    expect(screen.getByText('GraphiQL')).toBeInTheDocument();
+  });
+
+  it('renders the version pill when provided', () => {
+    render(<TopBarView {...DEFAULTS} version="v6.0.0-alpha.1" />);
+    expect(screen.getByText('v6.0.0-alpha.1')).toBeInTheDocument();
+  });
+
+  it('does not render the version pill when omitted', () => {
+    const { container } = render(<TopBarView {...DEFAULTS} />);
+    expect(container.querySelector('.graphiql-top-bar-version')).toBeNull();
+  });
+
+  it('renders the endpoint URL when provided', () => {
+    render(
+      <TopBarView
+        {...DEFAULTS}
+        endpointUrl="https://api.example.com/graphql"
+      />,
+    );
+    expect(
+      screen.getByText('https://api.example.com/graphql'),
+    ).toBeInTheDocument();
+  });
+
+  it('falls back to /graphql when endpointUrl is omitted', () => {
+    render(<TopBarView {...DEFAULTS} />);
+    expect(screen.getByText('/graphql')).toBeInTheDocument();
+  });
+
+  it('calls onRun when the Run button is clicked', async () => {
+    const user = userEvent.setup();
+    const onRun = vi.fn();
+    render(<TopBarView {...DEFAULTS} onRun={onRun} />);
+    await user.click(screen.getByRole('button', { name: /Run query/i }));
+    expect(onRun).toHaveBeenCalled();
+  });
+
+  it('disables the Run button while fetching', () => {
+    render(<TopBarView {...DEFAULTS} isFetching />);
+    expect(screen.getByRole('button', { name: /Run query/i })).toBeDisabled();
+  });
+
+  it('renders the command palette button', () => {
+    render(<TopBarView {...DEFAULTS} />);
+    expect(screen.getByText('Jump to schema')).toBeInTheDocument();
+  });
+
+  it('has role="banner" on the header element', () => {
+    const { container } = render(<TopBarView {...DEFAULTS} />);
+    expect(container.querySelector('header[role="banner"]')).not.toBeNull();
+  });
+});
diff --git a/packages/graphiql/src/GraphiQL.spec.tsx b/packages/graphiql/src/GraphiQL.spec.tsx
index 7bfcd8dd7a0..e46ad18ce31 100644
--- a/packages/graphiql/src/GraphiQL.spec.tsx
+++ b/packages/graphiql/src/GraphiQL.spec.tsx
@@ -181,9 +181,9 @@ describe('GraphiQL', () => {
           expect(queryEditor).toBeVisible();
           expect(queryEditor!.textContent).toBe('# Welcome to GraphiQL');
         },
-        { timeout: 15_000 },
+        { timeout: 25_000 },
       );
-    }, 20000);
+    }, 30000);
 
     it('accepts a custom default query', async () => {
       const { container } = render(
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index b12fb78a3a4..af7e1a66827 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -24,6 +24,7 @@ import {
   Tab,
   Tabs,
   Tooltip,
+  TopBar,
   UnStyledButton,
   useDragResize,
   useGraphiQL,
@@ -445,84 +446,87 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
   return (
     <Tooltip.Provider>
       <div className={cn('graphiql-container', className)}>
-        <Sidebar
-          forcedTheme={forcedTheme}
-          showPersistHeadersSettings={showPersistHeadersSettings}
-          setHiddenElement={pluginResize.setHiddenElement}
-        />
-        <div className="graphiql-main">
-          <div
-            ref={pluginResize.firstRef}
-            className="graphiql-plugin"
-            style={{
-              // Make sure the container shrinks when containing long
-              // non-breaking texts
-              minWidth: '200px',
-            }}
-          >
-            {PluginContent && <PluginContent />}
-          </div>
-          {visiblePlugin && (
-            <div
-              className="graphiql-horizontal-drag-bar"
-              ref={pluginResize.dragBarRef}
-            />
-          )}
-          <div ref={pluginResize.secondRef} className="graphiql-sessions">
-            <div className="graphiql-session-header">
-              <Tabs
-                ref={tabContainerRef}
-                values={tabs}
-                onReorder={moveTab}
-                aria-label="Select active operation"
-                className="no-scrollbar"
-              >
-                {tabs.map((tab, index, arr) => (
-                  <Tab
-                    key={tab.id}
-                    // Prevent overscroll over container
-                    dragConstraints={tabContainerRef}
-                    value={tab}
-                    isActive={index === activeTabIndex}
-                  >
-                    <Tab.Button
-                      aria-controls="graphiql-session"
-                      id={`graphiql-session-tab-${index}`}
-                      title={tab.title}
-                      onClick={handleTabClick}
-                    >
-                      {tab.title}
-                    </Tab.Button>
-                    {arr.length > 1 && <Tab.Close onClick={handleTabClose} />}
-                  </Tab>
-                ))}
-              </Tabs>
-              <Tooltip label={LABEL.newTab}>
-                <UnStyledButton
-                  type="button"
-                  className="graphiql-tab-add"
-                  onClick={addTab}
-                  aria-label={LABEL.newTab}
-                >
-                  <PlusIcon aria-hidden="true" />
-                </UnStyledButton>
-              </Tooltip>
-              {logo}
-            </div>
+        <TopBar />
+        <div className="graphiql-body">
+          <Sidebar
+            forcedTheme={forcedTheme}
+            showPersistHeadersSettings={showPersistHeadersSettings}
+            setHiddenElement={pluginResize.setHiddenElement}
+          />
+          <div className="graphiql-main">
             <div
-              role="tabpanel"
-              id="graphiql-session" // used by aria-controls="graphiql-session"
-              aria-labelledby={`${TAB_CLASS_PREFIX}${activeTabIndex}`}
+              ref={pluginResize.firstRef}
+              className="graphiql-plugin"
+              style={{
+                // Make sure the container shrinks when containing long
+                // non-breaking texts
+                minWidth: '200px',
+              }}
             >
-              {editors}
+              {PluginContent && <PluginContent />}
+            </div>
+            {visiblePlugin && (
               <div
                 className="graphiql-horizontal-drag-bar"
-                ref={editorResize.dragBarRef}
+                ref={pluginResize.dragBarRef}
               />
-              <div className="graphiql-response" ref={editorResize.secondRef}>
-                {isFetching && <Spinner />}
-                <ResponseEditor responseTooltip={responseTooltip} />
-                {footer}
+            )}
+            <div ref={pluginResize.secondRef} className="graphiql-sessions">
+              <div className="graphiql-session-header">
+                <Tabs
+                  ref={tabContainerRef}
+                  values={tabs}
+                  onReorder={moveTab}
+                  aria-label="Select active operation"
+                  className="no-scrollbar"
+                >
+                  {tabs.map((tab, index, arr) => (
+                    <Tab
+                      key={tab.id}
+                      // Prevent overscroll over container
+                      dragConstraints={tabContainerRef}
+                      value={tab}
+                      isActive={index === activeTabIndex}
+                    >
+                      <Tab.Button
+                        aria-controls="graphiql-session"
+                        id={`graphiql-session-tab-${index}`}
+                        title={tab.title}
+                        onClick={handleTabClick}
+                      >
+                        {tab.title}
+                      </Tab.Button>
+                      {arr.length > 1 && <Tab.Close onClick={handleTabClose} />}
+                    </Tab>
+                  ))}
+                </Tabs>
+                <Tooltip label={LABEL.newTab}>
+                  <UnStyledButton
+                    type="button"
+                    className="graphiql-tab-add"
+                    onClick={addTab}
+                    aria-label={LABEL.newTab}
+                  >
+                    <PlusIcon aria-hidden="true" />
+                  </UnStyledButton>
+                </Tooltip>
+                {logo}
+              </div>
+              <div
+                role="tabpanel"
+                id="graphiql-session" // used by aria-controls="graphiql-session"
+                aria-labelledby={`${TAB_CLASS_PREFIX}${activeTabIndex}`}
+              >
+                {editors}
+                <div
+                  className="graphiql-horizontal-drag-bar"
+                  ref={editorResize.dragBarRef}
+                />
+                <div className="graphiql-response" ref={editorResize.secondRef}>
+                  {isFetching && <Spinner />}
+                  <ResponseEditor responseTooltip={responseTooltip} />
+                  {footer}
+                </div>
               </div>
             </div>
           </div>
diff --git a/packages/graphiql/src/graphiql.css b/packages/graphiql/src/graphiql.css
index 3c60e5bba22..913855d9ec3 100644
--- a/packages/graphiql/src/graphiql.css
+++ b/packages/graphiql/src/graphiql.css
@@ -2,12 +2,21 @@
 .graphiql-container {
   background-color: hsl(var(--color-base));
   display: flex;
+  flex-direction: column;
   height: 100%;
   margin: 0;
   overflow: hidden;
   width: 100%;
 }
 
+/* Sidebar + main content row (below the top bar) */
+.graphiql-container .graphiql-body {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+
 /* The sidebar */
 .graphiql-container .graphiql-sidebar {
   display: flex;
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index e5f0ff5d4b6..dd09dc713df 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -251,6 +251,7 @@ websockets
 wgutils
 wincent
 wonka
+wordmark
 yoshiakis
 zdravo
 zustand

From 3f79ce94bab865be1bceae2e2596414e3766fc6d Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 11:41:07 -0700
Subject: [PATCH 21/38] v6: Add `StatusBar` layout component (#4289)

## Summary

This PR adds a 24px footer pinned to the bottom of the GraphiQL app. It
shows the connection status (with a small dot indicator), schema type
count, plugin count, the document encoding, and the language label. The
outer container becomes a flex column with a new `graphiql-body` wrapper
for the sidebar-plus-main row, which keeps the status bar fixed beneath
a scrolling content area.

## Test plan

- [x] Open the [deploy
preview](https://deploy-preview-4289--graphiql-test.netlify.app).
Confirm the status bar appears at the bottom of the app and reads
"Disconnected" with a red dot before any schema loads.
- [x] In the deploy preview, the default endpoint should load a schema;
confirm the status flips to "Connected" with a green dot, and a schema
type count appears.
- [x] Resize the browser window narrow; confirm the status bar stays
pinned at the bottom and the content area above scrolls independently.
- [x] Open the settings dialog and toggle dark/light theme; confirm the
bar's chrome follows the active theme.

Refs: graphql/graphiql#4219
---
 .changeset/status-bar.md                      |  5 +
 .../graphiql-react/src/components/index.ts    |  2 +
 .../src/components/status-bar/index.css       | 42 ++++++++
 .../src/components/status-bar/index.tsx       | 58 +++++++++++
 .../status-bar/status-bar.stories.tsx         | 96 +++++++++++++++++++
 .../components/status-bar/status-bar.test.tsx | 88 +++++++++++++++++
 packages/graphiql/src/GraphiQL.tsx            |  2 +
 packages/graphiql/src/graphiql.css            |  4 +-
 resources/custom-words.txt                    |  1 +
 9 files changed, 296 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/status-bar.md
 create mode 100644 packages/graphiql-react/src/components/status-bar/index.css
 create mode 100644 packages/graphiql-react/src/components/status-bar/index.tsx
 create mode 100644 packages/graphiql-react/src/components/status-bar/status-bar.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/status-bar/status-bar.test.tsx

diff --git a/.changeset/status-bar.md b/.changeset/status-bar.md
new file mode 100644
index 00000000000..3b40337747e
--- /dev/null
+++ b/.changeset/status-bar.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `StatusBar` layout component: a 24px-tall footer at the bottom of the app showing connection status, schema type count, active plugin count, cursor position, and document metadata (encoding, indent, language label).
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index d3e9ce0937d..c3c83bf4b7c 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -31,3 +31,5 @@ export { MethodPill } from './method-pill';
 export type { MethodPillProps, Operation } from './method-pill';
 export { TopBar, TopBarView } from './top-bar';
 export type { TopBarProps, TopBarViewProps } from './top-bar';
+export { StatusBar, StatusBarView } from './status-bar';
+export type { StatusBarProps, StatusBarViewProps } from './status-bar';
diff --git a/packages/graphiql-react/src/components/status-bar/index.css b/packages/graphiql-react/src/components/status-bar/index.css
new file mode 100644
index 00000000000..c9d06eb0224
--- /dev/null
+++ b/packages/graphiql-react/src/components/status-bar/index.css
@@ -0,0 +1,42 @@
+.graphiql-status-bar {
+  display: flex;
+  align-items: center;
+  gap: var(--px-14);
+  height: var(--status-bar-height);
+  flex-shrink: 0;
+  padding: 0 var(--px-12);
+  background: oklch(var(--bg-elevated));
+  border-top: 1px solid oklch(var(--border-default));
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-eyebrow);
+}
+
+.graphiql-status-bar-spacer {
+  flex: 1;
+}
+
+.graphiql-status-bar-conn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  font-weight: 500;
+}
+
+.graphiql-status-bar-conn-dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+}
+
+.graphiql-status-bar-conn.connected .graphiql-status-bar-conn-dot {
+  background: oklch(var(--accent-green));
+}
+
+.graphiql-status-bar-conn.disconnected .graphiql-status-bar-conn-dot {
+  background: oklch(var(--accent-red));
+}
+
+.graphiql-status-bar-plugins {
+  color: oklch(var(--accent-purple));
+}
diff --git a/packages/graphiql-react/src/components/status-bar/index.tsx b/packages/graphiql-react/src/components/status-bar/index.tsx
new file mode 100644
index 00000000000..4504d6a00fa
--- /dev/null
+++ b/packages/graphiql-react/src/components/status-bar/index.tsx
@@ -0,0 +1,58 @@
+'use no memo';
+
+import type { FC } from 'react';
+import { useGraphiQL } from '../provider';
+import './index.css';
+
+export type StatusBarProps = {
+  encoding?: string;
+};
+
+export type StatusBarViewProps = StatusBarProps & {
+  isConnected: boolean;
+  typeCount: number;
+  pluginCount: number;
+};
+
+export const StatusBarView: FC<StatusBarViewProps> = ({
+  isConnected,
+  typeCount,
+  pluginCount,
+  encoding = 'UTF-8',
+}) => (
+  <footer className="graphiql-status-bar" role="contentinfo">
+    <span
+      className={`graphiql-status-bar-conn${isConnected ? ' connected' : ' disconnected'}`}
+    >
+      <span className="graphiql-status-bar-conn-dot" aria-hidden="true" />
+      {isConnected ? 'Connected' : 'Disconnected'}
+    </span>
+    {isConnected && (
+      <span className="graphiql-status-bar-types">{typeCount} types</span>
+    )}
+    {pluginCount > 0 && (
+      <span className="graphiql-status-bar-plugins">
+        {pluginCount} {pluginCount === 1 ? 'plugin' : 'plugins'}
+      </span>
+    )}
+    <span className="graphiql-status-bar-spacer" />
+    <span>{encoding}</span>
+    <span>GraphQL</span>
+  </footer>
+);
+
+export const StatusBar: FC<StatusBarProps> = props => {
+  const schema = useGraphiQL(state => state.schema);
+  const plugins = useGraphiQL(state => state.plugins);
+  const isConnected = schema != null;
+  const typeCount = schema ? Object.keys(schema.getTypeMap()).length : 0;
+
+  return (
+    <StatusBarView
+      {...props}
+      isConnected={isConnected}
+      typeCount={typeCount}
+      pluginCount={plugins.length}
+    />
+  );
+};
diff --git a/packages/graphiql-react/src/components/status-bar/status-bar.stories.tsx b/packages/graphiql-react/src/components/status-bar/status-bar.stories.tsx
new file mode 100644
index 00000000000..6353515c4dd
--- /dev/null
+++ b/packages/graphiql-react/src/components/status-bar/status-bar.stories.tsx
@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { buildSchema } from 'graphql';
+import { StatusBarView } from './';
+
+const SCHEMA = buildSchema(`
+  type Query {
+    hero: Character
+    heroes: [Character]
+    search(text: String): [SearchResult]
+  }
+
+  union SearchResult = Human | Droid
+
+  interface Character {
+    id: ID!
+    name: String!
+    friends: [Character]
+    appearsIn: [Episode]!
+  }
+
+  enum Episode { NEWHOPE EMPIRE JEDI }
+
+  type Human implements Character {
+    id: ID!
+    name: String!
+    friends: [Character]
+    appearsIn: [Episode]!
+    homePlanet: String
+    height(unit: LengthUnit = METER): Float
+    mass: Float
+    starships: [Starship]
+  }
+
+  type Droid implements Character {
+    id: ID!
+    name: String!
+    friends: [Character]
+    appearsIn: [Episode]!
+    primaryFunction: String
+  }
+
+  type Starship { id: ID! name: String! }
+
+  enum LengthUnit { METER FOOT }
+`);
+
+const typeCount = Object.keys(SCHEMA.getTypeMap()).length;
+
+const meta: Meta<typeof StatusBarView> = {
+  title: 'Layout/StatusBar',
+  component: StatusBarView,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <div style={{ position: 'relative' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof StatusBarView>;
+
+export const Disconnected: Story = {
+  args: {
+    isConnected: false,
+    typeCount: 0,
+    pluginCount: 0,
+  },
+};
+
+export const Connected: Story = {
+  args: {
+    isConnected: true,
+    typeCount,
+    pluginCount: 0,
+  },
+};
+
+export const WithPlugins: Story = {
+  args: {
+    isConnected: true,
+    typeCount,
+    pluginCount: 2,
+  },
+};
+
+export const CustomEncoding: Story = {
+  args: {
+    isConnected: false,
+    typeCount: 0,
+    pluginCount: 0,
+    encoding: 'UTF-16',
+  },
+};
diff --git a/packages/graphiql-react/src/components/status-bar/status-bar.test.tsx b/packages/graphiql-react/src/components/status-bar/status-bar.test.tsx
new file mode 100644
index 00000000000..bb15d1df3cb
--- /dev/null
+++ b/packages/graphiql-react/src/components/status-bar/status-bar.test.tsx
@@ -0,0 +1,88 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { buildSchema } from 'graphql';
+import { StatusBarView } from './';
+
+const SCHEMA = buildSchema(`type Query { hello: String }`);
+
+const CONNECTED_DEFAULTS = {
+  isConnected: true,
+  typeCount: Object.keys(SCHEMA.getTypeMap()).length,
+  pluginCount: 0,
+};
+
+const DISCONNECTED_DEFAULTS = {
+  isConnected: false,
+  typeCount: 0,
+  pluginCount: 0,
+};
+
+describe('StatusBarView', () => {
+  it('shows "Disconnected" when not connected', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.getByText('Disconnected')).toBeInTheDocument();
+  });
+
+  it('shows "Connected" when connected', () => {
+    render(<StatusBarView {...CONNECTED_DEFAULTS} />);
+    expect(screen.getByText('Connected')).toBeInTheDocument();
+  });
+
+  it('shows type count when connected', () => {
+    render(<StatusBarView {...CONNECTED_DEFAULTS} />);
+    expect(
+      screen.getByText(`${CONNECTED_DEFAULTS.typeCount} types`),
+    ).toBeInTheDocument();
+  });
+
+  it('does not show type count when disconnected', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.queryByText(/types/)).toBeNull();
+  });
+
+  it('shows plugin count when plugins are registered', () => {
+    render(<StatusBarView {...CONNECTED_DEFAULTS} pluginCount={2} />);
+    expect(screen.getByText('2 plugins')).toBeInTheDocument();
+  });
+
+  it('uses singular "plugin" for one plugin', () => {
+    render(<StatusBarView {...CONNECTED_DEFAULTS} pluginCount={1} />);
+    expect(screen.getByText('1 plugin')).toBeInTheDocument();
+  });
+
+  it('does not show plugin count when no plugins are registered', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.queryByText(/plugin/)).toBeNull();
+  });
+
+  it('shows default encoding', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.getByText('UTF-8')).toBeInTheDocument();
+  });
+
+  it('shows custom encoding', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} encoding="UTF-16" />);
+    expect(screen.getByText('UTF-16')).toBeInTheDocument();
+  });
+
+  it('renders a status dot inside the connection label', () => {
+    const { container } = render(<StatusBarView {...CONNECTED_DEFAULTS} />);
+    expect(
+      container.querySelector(
+        '.graphiql-status-bar-conn.connected .graphiql-status-bar-conn-dot',
+      ),
+    ).not.toBeNull();
+  });
+
+  it('always shows the GraphQL language label', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.getByText('GraphQL')).toBeInTheDocument();
+  });
+
+  it('renders as a footer with role contentinfo', () => {
+    render(<StatusBarView {...DISCONNECTED_DEFAULTS} />);
+    expect(screen.getByRole('contentinfo')).toBeInTheDocument();
+  });
+});
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index af7e1a66827..5b13baa4c83 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -21,6 +21,7 @@ import {
   QueryEditor,
   ResponseEditor,
   Spinner,
+  StatusBar,
   Tab,
   Tabs,
   Tooltip,
@@ -531,6 +532,7 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
             </div>
           </div>
         </div>
+        <StatusBar />
       </div>
       {children}
     </Tooltip.Provider>
diff --git a/packages/graphiql/src/graphiql.css b/packages/graphiql/src/graphiql.css
index 913855d9ec3..ed24fd51d1f 100644
--- a/packages/graphiql/src/graphiql.css
+++ b/packages/graphiql/src/graphiql.css
@@ -9,7 +9,7 @@
   width: 100%;
 }
 
-/* Sidebar + main content row (below the top bar) */
+/* Sidebar + main content row (below the top bar and above the status bar) */
 .graphiql-container .graphiql-body {
   display: flex;
   flex: 1;
@@ -201,7 +201,7 @@ button.graphiql-tab-add {
 
 /* The response view */
 .graphiql-container .graphiql-response {
-  /* Add some padding so it doesn’t touch the tabs */
+  /* Add some padding so it doesn't touch the tabs */
   padding-top: var(--px-16);
   display: flex;
   width: 100%;
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index dd09dc713df..579f8f0c425 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -211,6 +211,7 @@ sonarjs
 sorare
 spawndamnit
 squirrelly
+starships
 stonexer
 streamable
 subword

From bbe02de17c9cbb01ba4dfc23be3b9ed82e9b7055 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 12:03:05 -0700
Subject: [PATCH 22/38] v6: Add `ActivityRail` and replace the previous sidebar
 (#4290)

## Summary

This PR replaces the v5 sidebar icon strip with a new `ActivityRail`
that renders registered plugins as a flat list with the settings gear
pinned at the bottom. An `ActivityBar` wrapper in the `graphiql` package
owns the resize sync and the settings/theme dialogs that previously
lived inside the old `Sidebar`. There are no plugin API changes;
registered plugins continue to render through the existing `plugins`
array.

## Test plan

- [x] Open the [deploy
preview](https://deploy-preview-4290--graphiql-test.netlify.app).
Confirm the activity rail renders along the left edge with each plugin's
icon and the settings gear at the bottom.
- [x] Click between plugin icons; confirm the active plugin shows the
accent indicator and the panel content swaps.
- [x] Click the settings gear; confirm the settings dialog opens.
- [x] Drag the divider between the panel and the editor area; confirm
the rail stays put and the side panel resizes.
- [x] Toggle dark/light theme via the settings dialog; confirm the rail
reads from the active tokens in both modes.

Refs: graphql/graphiql#4219
---
 .changeset/activity-rail.md                   |   8 ++
 .../activity-rail/activity-rail.stories.tsx   | 117 +++++++++++++++
 .../activity-rail/activity-rail.test.tsx      | 132 +++++++++++++++++
 .../src/components/activity-rail/index.css    |  97 +++++++++++++
 .../src/components/activity-rail/index.tsx    |  71 +++++++++
 .../graphiql-react/src/components/index.ts    |   2 +
 packages/graphiql/cypress/e2e/a11y.cy.ts      |   2 +-
 packages/graphiql/cypress/e2e/docs.cy.ts      |  10 +-
 packages/graphiql/cypress/e2e/theme.cy.ts     |   2 +-
 packages/graphiql/src/GraphiQL.spec.tsx       |  12 +-
 packages/graphiql/src/GraphiQL.tsx            |  11 +-
 packages/graphiql/src/graphiql.css            |  33 +----
 .../src/ui/{sidebar.tsx => activity-bar.tsx}  | 135 ++++--------------
 packages/graphiql/src/ui/index.ts             |   3 +-
 14 files changed, 474 insertions(+), 161 deletions(-)
 create mode 100644 .changeset/activity-rail.md
 create mode 100644 packages/graphiql-react/src/components/activity-rail/activity-rail.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/activity-rail/activity-rail.test.tsx
 create mode 100644 packages/graphiql-react/src/components/activity-rail/index.css
 create mode 100644 packages/graphiql-react/src/components/activity-rail/index.tsx
 rename packages/graphiql/src/ui/{sidebar.tsx => activity-bar.tsx} (67%)

diff --git a/.changeset/activity-rail.md b/.changeset/activity-rail.md
new file mode 100644
index 00000000000..797ea3b92f7
--- /dev/null
+++ b/.changeset/activity-rail.md
@@ -0,0 +1,8 @@
+---
+'@graphiql/react': minor
+'graphiql': major
+---
+
+Replace the left-side plugin sidebar with `ActivityRail`. Plugins render as a flat list in registration order with a 2px blue left border on the active plugin. Settings gear at the bottom opens the settings dialog.
+
+The previous `graphiql-sidebar` DOM structure and CSS class names are removed. Custom CSS overrides targeting `.graphiql-sidebar` or its children will need updating. Only CSS variable names are part of the public API.
diff --git a/packages/graphiql-react/src/components/activity-rail/activity-rail.stories.tsx b/packages/graphiql-react/src/components/activity-rail/activity-rail.stories.tsx
new file mode 100644
index 00000000000..8ebcf7ab1fb
--- /dev/null
+++ b/packages/graphiql-react/src/components/activity-rail/activity-rail.stories.tsx
@@ -0,0 +1,117 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import {
+  DocsIcon,
+  HistoryIcon,
+  StarIcon,
+  MagnifyingGlassIcon,
+  SettingsIcon,
+} from '../../icons';
+import { Tooltip } from '../tooltip';
+import './index.css';
+
+type Plugin = { title: string; icon: React.ComponentType };
+
+const SAMPLE_PLUGINS: Plugin[] = [
+  { title: 'Documentation Explorer', icon: DocsIcon },
+  { title: 'History', icon: HistoryIcon },
+  { title: 'Favorites', icon: StarIcon },
+  { title: 'Search', icon: MagnifyingGlassIcon },
+];
+
+function ActivityRailDemo({
+  initialActive,
+  showSettings = true,
+}: {
+  initialActive?: string;
+  showSettings?: boolean;
+}) {
+  const [active, setActive] = useState<string | null>(initialActive ?? null);
+
+  function toggle(title: string) {
+    setActive(prev => (prev === title ? null : title));
+  }
+
+  return (
+    <Tooltip.Provider>
+      <div style={{ display: 'flex', height: 400 }}>
+        <nav className="graphiql-activity-rail" aria-label="Plugins">
+          <ul className="graphiql-activity-rail-list">
+            {SAMPLE_PLUGINS.map(plugin => {
+              const Icon = plugin.icon;
+              const isActive = active === plugin.title;
+              const label = `${isActive ? 'Hide' : 'Show'} ${plugin.title}`;
+              return (
+                <li key={plugin.title}>
+                  <Tooltip label={label}>
+                    <button
+                      type="button"
+                      className={`graphiql-activity-rail-item${isActive ? ' active' : ''}`}
+                      aria-pressed={isActive}
+                      aria-label={label}
+                      onClick={() => toggle(plugin.title)}
+                    >
+                      <Icon aria-hidden="true" />
+                    </button>
+                  </Tooltip>
+                </li>
+              );
+            })}
+          </ul>
+          <div className="graphiql-activity-rail-spacer" />
+          {showSettings && (
+            <Tooltip label="Settings">
+              <button
+                type="button"
+                className="graphiql-activity-rail-settings"
+                aria-label="Settings"
+              >
+                <SettingsIcon aria-hidden="true" />
+              </button>
+            </Tooltip>
+          )}
+        </nav>
+        {active && (
+          <div
+            style={{
+              padding: 16,
+              borderRight: '1px solid oklch(var(--border-default))',
+            }}
+          >
+            <strong>{active}</strong> panel
+          </div>
+        )}
+      </div>
+    </Tooltip.Provider>
+  );
+}
+
+const meta: Meta = {
+  title: 'Components/ActivityRail',
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj = {
+  render: () => <ActivityRailDemo />,
+};
+
+export const WithActivePlugin: StoryObj = {
+  render: () => <ActivityRailDemo initialActive="Documentation Explorer" />,
+};
+
+export const NoPluginsNoSettings: StoryObj = {
+  render: () => (
+    <Tooltip.Provider>
+      <div style={{ display: 'flex', height: 400 }}>
+        <nav className="graphiql-activity-rail" aria-label="Plugins">
+          <ul className="graphiql-activity-rail-list" />
+          <div className="graphiql-activity-rail-spacer" />
+        </nav>
+      </div>
+    </Tooltip.Provider>
+  ),
+};
diff --git a/packages/graphiql-react/src/components/activity-rail/activity-rail.test.tsx b/packages/graphiql-react/src/components/activity-rail/activity-rail.test.tsx
new file mode 100644
index 00000000000..e171336275c
--- /dev/null
+++ b/packages/graphiql-react/src/components/activity-rail/activity-rail.test.tsx
@@ -0,0 +1,132 @@
+'use no memo';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import * as T from '@radix-ui/react-tooltip';
+import type { ReactNode } from 'react';
+import type { GraphiQLPlugin } from '../../stores/plugin';
+import { ActivityRail } from './';
+
+const DocsIcon = () => <svg data-testid="docs-icon" />;
+const HistoryIcon = () => <svg data-testid="history-icon" />;
+
+const DOCS_PLUGIN: GraphiQLPlugin = {
+  title: 'Documentation Explorer',
+  icon: DocsIcon,
+  content: () => null,
+};
+
+const HISTORY_PLUGIN: GraphiQLPlugin = {
+  title: 'History',
+  icon: HistoryIcon,
+  content: () => null,
+};
+
+const mockSetVisiblePlugin = vi.fn();
+
+vi.mock('../provider', () => ({
+  useGraphiQL: vi.fn(),
+  useGraphiQLActions: vi.fn(),
+}));
+
+import { useGraphiQL, useGraphiQLActions } from '../provider';
+
+const mockUseGraphiQL = vi.mocked(useGraphiQL);
+const mockUseGraphiQLActions = vi.mocked(useGraphiQLActions);
+
+function renderWithProvider(ui: ReactNode) {
+  return render(<T.Provider>{ui}</T.Provider>);
+}
+
+function setup(visiblePlugin: GraphiQLPlugin | null = null) {
+  mockUseGraphiQL.mockImplementation((selector: (s: any) => any) => {
+    const state = {
+      plugins: [DOCS_PLUGIN, HISTORY_PLUGIN],
+      visiblePlugin,
+    };
+    return selector(state);
+  });
+  mockUseGraphiQLActions.mockReturnValue({
+    setVisiblePlugin: mockSetVisiblePlugin,
+  } as any);
+}
+
+describe('ActivityRail', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders a button for each plugin', () => {
+    setup();
+    renderWithProvider(<ActivityRail />);
+    expect(
+      screen.getByRole('button', { name: 'Show Documentation Explorer' }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: 'Show History' }),
+    ).toBeInTheDocument();
+  });
+
+  it('marks the active plugin with aria-pressed=true', () => {
+    setup(DOCS_PLUGIN);
+    renderWithProvider(<ActivityRail />);
+    expect(
+      screen.getByRole('button', { name: 'Hide Documentation Explorer' }),
+    ).toHaveAttribute('aria-pressed', 'true');
+    expect(
+      screen.getByRole('button', { name: 'Show History' }),
+    ).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('calls setVisiblePlugin with the plugin when an inactive button is clicked', async () => {
+    const user = userEvent.setup();
+    setup(null);
+    renderWithProvider(<ActivityRail />);
+    await user.click(
+      screen.getByRole('button', { name: 'Show Documentation Explorer' }),
+    );
+    expect(mockSetVisiblePlugin).toHaveBeenCalledWith(DOCS_PLUGIN);
+  });
+
+  it('calls setVisiblePlugin(null) when the active plugin button is clicked', async () => {
+    const user = userEvent.setup();
+    setup(DOCS_PLUGIN);
+    renderWithProvider(<ActivityRail />);
+    await user.click(
+      screen.getByRole('button', { name: 'Hide Documentation Explorer' }),
+    );
+    expect(mockSetVisiblePlugin).toHaveBeenCalledWith(null);
+  });
+
+  it('renders inside a <nav> with aria-label="Plugins"', () => {
+    setup();
+    renderWithProvider(<ActivityRail />);
+    expect(
+      screen.getByRole('navigation', { name: 'Plugins' }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders the settings button when onSettingsClick is provided', () => {
+    setup();
+    renderWithProvider(<ActivityRail onSettingsClick={vi.fn()} />);
+    expect(
+      screen.getByRole('button', { name: 'Settings' }),
+    ).toBeInTheDocument();
+  });
+
+  it('does not render the settings button without onSettingsClick', () => {
+    setup();
+    renderWithProvider(<ActivityRail />);
+    expect(screen.queryByRole('button', { name: 'Settings' })).toBeNull();
+  });
+
+  it('calls onSettingsClick when the settings button is clicked', async () => {
+    const user = userEvent.setup();
+    const onSettingsClick = vi.fn();
+    setup();
+    renderWithProvider(<ActivityRail onSettingsClick={onSettingsClick} />);
+    await user.click(screen.getByRole('button', { name: 'Settings' }));
+    expect(onSettingsClick).toHaveBeenCalledOnce();
+  });
+});
diff --git a/packages/graphiql-react/src/components/activity-rail/index.css b/packages/graphiql-react/src/components/activity-rail/index.css
new file mode 100644
index 00000000000..65a09f19a2d
--- /dev/null
+++ b/packages/graphiql-react/src/components/activity-rail/index.css
@@ -0,0 +1,97 @@
+.graphiql-activity-rail {
+  display: flex;
+  flex-direction: column;
+  width: var(--rail-width);
+  padding: var(--px-8) 0;
+  background: oklch(var(--bg-elevated));
+  border-right: 1px solid oklch(var(--border-default));
+  flex-shrink: 0;
+}
+
+.graphiql-activity-rail-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--px-4);
+  align-items: center;
+}
+
+.graphiql-activity-rail-item {
+  width: 32px;
+  height: 32px;
+  border: 0;
+  border-left: 2px solid transparent;
+  margin-left: -2px;
+  background: transparent;
+  color: oklch(var(--fg-subtle));
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  transition:
+    color 120ms ease,
+    background 120ms ease;
+}
+
+.graphiql-activity-rail-item:hover {
+  color: oklch(var(--fg-default));
+  background: oklch(var(--bg-subtle));
+}
+
+.graphiql-activity-rail-item:focus-visible {
+  outline: 2px solid oklch(var(--accent-blue));
+  outline-offset: 2px;
+}
+
+.graphiql-activity-rail-item.active {
+  background: oklch(var(--bg-subtle));
+  color: oklch(var(--fg-strong));
+  border-left-color: oklch(var(--accent-blue));
+  border-radius: 0 var(--radius-md) var(--radius-md) 0;
+}
+
+.graphiql-activity-rail-item svg {
+  width: 16px;
+  height: 16px;
+}
+
+.graphiql-activity-rail-spacer {
+  flex: 1;
+}
+
+.graphiql-activity-rail-settings {
+  width: 32px;
+  height: 32px;
+  margin: 0 auto;
+  border: 0;
+  background: transparent;
+  color: oklch(var(--fg-subtle));
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border-radius: var(--radius-md);
+  transition:
+    color 120ms ease,
+    background 120ms ease;
+}
+
+.graphiql-activity-rail-settings:hover {
+  color: oklch(var(--fg-default));
+  background: oklch(var(--bg-subtle));
+}
+
+.graphiql-activity-rail-settings:focus-visible {
+  outline: 2px solid oklch(var(--accent-blue));
+  outline-offset: 2px;
+}
+
+.graphiql-activity-rail-settings svg {
+  width: 16px;
+  height: 16px;
+}
diff --git a/packages/graphiql-react/src/components/activity-rail/index.tsx b/packages/graphiql-react/src/components/activity-rail/index.tsx
new file mode 100644
index 00000000000..62c60d1db47
--- /dev/null
+++ b/packages/graphiql-react/src/components/activity-rail/index.tsx
@@ -0,0 +1,71 @@
+'use no memo';
+
+import type { FC } from 'react';
+import { useGraphiQL, useGraphiQLActions } from '../provider';
+import type { GraphiQLPlugin } from '../../stores/plugin';
+import { Tooltip } from '../tooltip';
+import { SettingsIcon } from '../../icons';
+import './index.css';
+
+export interface ActivityRailProps {
+  /**
+   * Called when a plugin button is clicked, after the store has been updated.
+   * Receives the plugin that is now visible, or `null` if the panel was closed.
+   */
+  onPluginToggle?: (nextPlugin: GraphiQLPlugin | null) => void;
+  /** Called when the settings gear button is clicked. */
+  onSettingsClick?: () => void;
+}
+
+export const ActivityRail: FC<ActivityRailProps> = ({
+  onPluginToggle,
+  onSettingsClick,
+}) => {
+  const plugins = useGraphiQL(state => state.plugins);
+  const visiblePlugin = useGraphiQL(state => state.visiblePlugin);
+  const { setVisiblePlugin } = useGraphiQLActions();
+
+  return (
+    <nav className="graphiql-activity-rail" aria-label="Plugins">
+      <ul className="graphiql-activity-rail-list">
+        {plugins.map(plugin => {
+          const Icon = plugin.icon;
+          const isActive = visiblePlugin?.title === plugin.title;
+          const label = `${isActive ? 'Hide' : 'Show'} ${plugin.title}`;
+          const nextPlugin = isActive ? null : plugin;
+          return (
+            <li key={plugin.title}>
+              <Tooltip label={label}>
+                <button
+                  type="button"
+                  className={`graphiql-activity-rail-item${isActive ? ' active' : ''}`}
+                  aria-pressed={isActive}
+                  aria-label={label}
+                  onClick={() => {
+                    setVisiblePlugin(nextPlugin);
+                    onPluginToggle?.(nextPlugin);
+                  }}
+                >
+                  <Icon aria-hidden="true" />
+                </button>
+              </Tooltip>
+            </li>
+          );
+        })}
+      </ul>
+      <div className="graphiql-activity-rail-spacer" />
+      {onSettingsClick && (
+        <Tooltip label="Settings">
+          <button
+            type="button"
+            className="graphiql-activity-rail-settings"
+            aria-label="Settings"
+            onClick={onSettingsClick}
+          >
+            <SettingsIcon aria-hidden="true" />
+          </button>
+        </Tooltip>
+      )}
+    </nav>
+  );
+};
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index c3c83bf4b7c..dd4ace671cf 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -33,3 +33,5 @@ export { TopBar, TopBarView } from './top-bar';
 export type { TopBarProps, TopBarViewProps } from './top-bar';
 export { StatusBar, StatusBarView } from './status-bar';
 export type { StatusBarProps, StatusBarViewProps } from './status-bar';
+export { ActivityRail } from './activity-rail';
+export type { ActivityRailProps } from './activity-rail';
diff --git a/packages/graphiql/cypress/e2e/a11y.cy.ts b/packages/graphiql/cypress/e2e/a11y.cy.ts
index 9474b9c169f..b8c952b20f1 100644
--- a/packages/graphiql/cypress/e2e/a11y.cy.ts
+++ b/packages/graphiql/cypress/e2e/a11y.cy.ts
@@ -88,7 +88,7 @@ describe('a11y baseline', () => {
 
   it('with docs panel open has no new violations', () => {
     // First sidebar button is the docs explorer toggle (confirmed in docs.cy.ts)
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
     cy.get('.graphiql-doc-explorer').should('be.visible');
     cy.injectAxe();
     checkOrCapture('docs-open');
diff --git a/packages/graphiql/cypress/e2e/docs.cy.ts b/packages/graphiql/cypress/e2e/docs.cy.ts
index 1dc8824d0f6..031113d68a5 100644
--- a/packages/graphiql/cypress/e2e/docs.cy.ts
+++ b/packages/graphiql/cypress/e2e/docs.cy.ts
@@ -6,21 +6,21 @@ beforeEach(() => {
 
 describe('GraphiQL DocExplorer - button', () => {
   beforeEach(() => {
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
   });
   it('Toggles doc pane on', () => {
     cy.get('.graphiql-doc-explorer').should('be.visible');
   });
 
   it('Toggles doc pane back off', () => {
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
     cy.get('.graphiql-doc-explorer').should('not.exist');
   });
 });
 
 describe('GraphiQL DocExplorer - search', () => {
   beforeEach(() => {
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
     cy.dataCy('doc-explorer-input').type('test');
     cy.dataCy('doc-explorer-option').should('have.length', 7);
   });
@@ -71,7 +71,7 @@ describe('GraphiQL DocExplorer - search', () => {
 describe('GraphQL DocExplorer - deprecated fields', () => {
   it('should show deprecated fields details when expanding', () => {
     // Open doc explorer
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
 
     // Select query type
     cy.get('.graphiql-doc-explorer-type-name').first().click();
@@ -105,7 +105,7 @@ if (!version.includes('15.5')) {
 describeOrSkip('GraphQL DocExplorer - deprecated arguments', () => {
   it('should show deprecated arguments category title', () => {
     // Open doc explorer
-    cy.get('.graphiql-sidebar button').eq(0).click();
+    cy.get('.graphiql-activity-rail-item').eq(0).click();
 
     // Select query type
     cy.get('.graphiql-doc-explorer-type-name').first().click();
diff --git a/packages/graphiql/cypress/e2e/theme.cy.ts b/packages/graphiql/cypress/e2e/theme.cy.ts
index a59658db98e..d9b751f19bf 100644
--- a/packages/graphiql/cypress/e2e/theme.cy.ts
+++ b/packages/graphiql/cypress/e2e/theme.cy.ts
@@ -12,7 +12,7 @@ describe('Theme', () => {
 
     it('Defaults to light theme when `forcedTheme` value is invalid', () => {
       cy.visit('?forcedTheme=invalid');
-      cy.get('[data-value=settings]').click();
+      cy.get('.graphiql-activity-rail-settings').click();
       cy.get('.graphiql-dialog-section-title')
         .eq(1)
         .should('have.text', 'Theme'); // Check for the presence of the theme dialog
diff --git a/packages/graphiql/src/GraphiQL.spec.tsx b/packages/graphiql/src/GraphiQL.spec.tsx
index e46ad18ce31..c393dfa3f14 100644
--- a/packages/graphiql/src/GraphiQL.spec.tsx
+++ b/packages/graphiql/src/GraphiQL.spec.tsx
@@ -390,9 +390,7 @@ describe('GraphiQL', () => {
     );
 
     act(() => {
-      fireEvent.click(
-        container.querySelector('[aria-label="Open settings dialog"]')!,
-      );
+      fireEvent.click(container.querySelector('[aria-label="Settings"]')!);
     });
 
     const element = await findByText('Persist headers');
@@ -405,9 +403,7 @@ describe('GraphiQL', () => {
     );
 
     act(() => {
-      fireEvent.click(
-        container.querySelector('[aria-label="Open settings dialog"]')!,
-      );
+      fireEvent.click(container.querySelector('[aria-label="Settings"]')!);
     });
 
     const element = await findByText('Persist headers');
@@ -420,9 +416,7 @@ describe('GraphiQL', () => {
     );
 
     act(() => {
-      fireEvent.click(
-        container.querySelector('[aria-label="Open settings dialog"]')!,
-      );
+      fireEvent.click(container.querySelector('[aria-label="Settings"]')!);
     });
 
     const callback = async () => {
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index 5b13baa4c83..a9b09616dd0 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -41,7 +41,12 @@ import {
   DocExplorerStore,
   DOC_EXPLORER_PLUGIN,
 } from '@graphiql/plugin-doc-explorer';
-import { GraphiQLLogo, GraphiQLToolbar, GraphiQLFooter, Sidebar } from './ui';
+import {
+  ActivityBar,
+  GraphiQLLogo,
+  GraphiQLToolbar,
+  GraphiQLFooter,
+} from './ui';
 
 /**
  * API docs for this live here:
@@ -152,7 +157,7 @@ export interface GraphiQLInterfaceProps
     AddSuffix<Pick<HeaderEditorProps, 'onEdit'>, 'Headers'>,
     Pick<ResponseEditorProps, 'responseTooltip'>,
     Pick<
-      ComponentPropsWithoutRef<typeof Sidebar>,
+      ComponentPropsWithoutRef<typeof ActivityBar>,
       'forcedTheme' | 'showPersistHeadersSettings'
     > {
   children?: ReactNode;
@@ -449,7 +454,7 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
       <div className={cn('graphiql-container', className)}>
         <TopBar />
         <div className="graphiql-body">
-          <Sidebar
+          <ActivityBar
             forcedTheme={forcedTheme}
             showPersistHeadersSettings={showPersistHeadersSettings}
             setHiddenElement={pluginResize.setHiddenElement}
diff --git a/packages/graphiql/src/graphiql.css b/packages/graphiql/src/graphiql.css
index ed24fd51d1f..8ea0d9ab560 100644
--- a/packages/graphiql/src/graphiql.css
+++ b/packages/graphiql/src/graphiql.css
@@ -9,7 +9,7 @@
   width: 100%;
 }
 
-/* Sidebar + main content row (below the top bar and above the status bar) */
+/* Activity rail + main content row (below the top bar and above the status bar) */
 .graphiql-container .graphiql-body {
   display: flex;
   flex: 1;
@@ -17,36 +17,7 @@
   overflow: hidden;
 }
 
-/* The sidebar */
-.graphiql-container .graphiql-sidebar {
-  display: flex;
-  flex-direction: column;
-  padding: var(--px-8);
-  width: var(--sidebar-width);
-  gap: var(--px-8);
-  overflow-y: auto;
-}
-
-.graphiql-container .graphiql-sidebar > button {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
-  height: calc(var(--sidebar-width) - (2 * var(--px-8)));
-  width: calc(var(--sidebar-width) - (2 * var(--px-8)));
-  flex-shrink: 0;
-}
-
-.graphiql-container .graphiql-sidebar button.active {
-  color: hsl(var(--color-neutral));
-}
-
-.graphiql-container .graphiql-sidebar button > svg {
-  height: var(--px-20);
-  width: var(--px-20);
-}
-
-/* The main content, i.e. everything except the sidebar */
+/* The main content, i.e. everything except the activity rail */
 .graphiql-container .graphiql-main {
   display: flex;
   flex: 1;
diff --git a/packages/graphiql/src/ui/sidebar.tsx b/packages/graphiql/src/ui/activity-bar.tsx
similarity index 67%
rename from packages/graphiql/src/ui/sidebar.tsx
rename to packages/graphiql/src/ui/activity-bar.tsx
index 7551ee51c78..b4525177ea5 100644
--- a/packages/graphiql/src/ui/sidebar.tsx
+++ b/packages/graphiql/src/ui/activity-bar.tsx
@@ -1,35 +1,23 @@
-import { FC, type MouseEventHandler, useEffect, useState } from 'react';
+import { type FC, type MouseEventHandler, useEffect, useState } from 'react';
 import {
+  ActivityRail,
   Button,
   ButtonGroup,
   cn,
   Dialog,
   isMacOs,
-  KEY_MAP,
-  KeyboardShortcutIcon,
   pick,
-  ReloadIcon,
-  SettingsIcon,
-  Tooltip,
-  UnStyledButton,
-  useDragResize,
   useGraphiQL,
   useGraphiQLActions,
+  useDragResize,
   VisuallyHidden,
+  type GraphiQLPlugin,
 } from '@graphiql/react';
 import { ShortKeys } from './short-keys';
 
-type ButtonHandler = MouseEventHandler<HTMLButtonElement>;
-
-const LABEL = {
-  refetchSchema: `Re-fetch GraphQL schema (${KEY_MAP.refetchSchema.key})`,
-  shortCutDialog: 'Open short keys dialog',
-  settingsDialogs: 'Open settings dialog',
-};
-
 const THEMES = ['light', 'dark', 'system'] as const;
 
-interface SidebarProps {
+export interface ActivityBarProps {
   /**
    * `forcedTheme` allows enforcement of a specific theme for GraphiQL.
    * This is useful when you want to make sure that GraphiQL is always
@@ -46,31 +34,19 @@ interface SidebarProps {
   setHiddenElement: ReturnType<typeof useDragResize>['setHiddenElement'];
 }
 
-export const Sidebar: FC<SidebarProps> = ({
+type ButtonHandler = MouseEventHandler<HTMLButtonElement>;
+
+export const ActivityBar: FC<ActivityBarProps> = ({
   forcedTheme: $forcedTheme,
   showPersistHeadersSettings,
   setHiddenElement,
 }) => {
   const forcedTheme =
     $forcedTheme && THEMES.includes($forcedTheme) ? $forcedTheme : undefined;
-  const { setShouldPersistHeaders, introspect, setVisiblePlugin, setTheme } =
-    useGraphiQLActions();
-  const {
-    shouldPersistHeaders,
-    isIntrospecting,
-    visiblePlugin,
-    plugins,
-    theme,
-    storage,
-  } = useGraphiQL(
-    pick(
-      'shouldPersistHeaders',
-      'isIntrospecting',
-      'visiblePlugin',
-      'plugins',
-      'theme',
-      'storage',
-    ),
+
+  const { setShouldPersistHeaders, setTheme } = useGraphiQLActions();
+  const { shouldPersistHeaders, theme, storage } = useGraphiQL(
+    pick('shouldPersistHeaders', 'theme', 'storage'),
   );
 
   useEffect(() => {
@@ -91,27 +67,26 @@ export const Sidebar: FC<SidebarProps> = ({
   useEffect(() => {
     function openSettings(event: KeyboardEvent) {
       if ((isMacOs ? event.metaKey : event.ctrlKey) && event.key === ',') {
-        event.preventDefault(); // prevent default browser settings dialog
+        event.preventDefault();
         setShowDialog(prev => (prev === 'settings' ? null : 'settings'));
       }
     }
-
     window.addEventListener('keydown', openSettings);
     return () => {
       window.removeEventListener('keydown', openSettings);
     };
   }, []);
 
-  function handleOpenShortKeysDialog(isOpen: boolean) {
+  function handleOpenSettingsDialog(isOpen: boolean) {
     if (!isOpen) {
       setShowDialog(null);
+      setClearStorageStatus(undefined);
     }
   }
 
-  function handleOpenSettingsDialog(isOpen: boolean) {
+  function handleOpenShortKeysDialog(isOpen: boolean) {
     if (!isOpen) {
       setShowDialog(null);
-      setClearStorageStatus(undefined);
     }
   }
 
@@ -136,78 +111,20 @@ export const Sidebar: FC<SidebarProps> = ({
     setTheme(selectedTheme || null);
   };
 
-  const handleShowDialog: ButtonHandler = event => {
-    setShowDialog(
-      event.currentTarget.dataset.value as 'short-keys' | 'settings',
-    );
-  };
-
-  const handlePluginClick: ButtonHandler = event => {
-    const pluginIndex = Number(event.currentTarget.dataset.index!);
-    const plugin = plugins.find((_, index) => pluginIndex === index)!;
-    const isVisible = plugin === visiblePlugin;
-    if (isVisible) {
-      setVisiblePlugin(null);
+  function handlePluginToggle(nextPlugin: GraphiQLPlugin | null) {
+    if (nextPlugin === null) {
       setHiddenElement('first');
     } else {
-      setVisiblePlugin(plugin);
       setHiddenElement(null);
     }
-  };
+  }
 
   return (
-    <div className="graphiql-sidebar">
-      {plugins.map((plugin, index) => {
-        const isVisible = plugin === visiblePlugin;
-        const label = `${isVisible ? 'Hide' : 'Show'} ${plugin.title}`;
-        return (
-          <Tooltip key={plugin.title} label={label}>
-            <UnStyledButton
-              type="button"
-              className={cn(isVisible && 'active')}
-              onClick={handlePluginClick}
-              data-index={index}
-              aria-label={label}
-            >
-              <plugin.icon aria-hidden="true" />
-            </UnStyledButton>
-          </Tooltip>
-        );
-      })}
-      <Tooltip label={LABEL.refetchSchema}>
-        <UnStyledButton
-          type="button"
-          disabled={isIntrospecting}
-          onClick={introspect}
-          aria-label={LABEL.refetchSchema}
-          style={{ marginTop: 'auto' }}
-        >
-          <ReloadIcon
-            className={cn(isIntrospecting && 'graphiql-spin')}
-            aria-hidden="true"
-          />
-        </UnStyledButton>
-      </Tooltip>
-      <Tooltip label={LABEL.shortCutDialog}>
-        <UnStyledButton
-          type="button"
-          data-value="short-keys"
-          onClick={handleShowDialog}
-          aria-label={LABEL.shortCutDialog}
-        >
-          <KeyboardShortcutIcon aria-hidden="true" />
-        </UnStyledButton>
-      </Tooltip>
-      <Tooltip label={LABEL.settingsDialogs}>
-        <UnStyledButton
-          type="button"
-          data-value="settings"
-          onClick={handleShowDialog}
-          aria-label={LABEL.settingsDialogs}
-        >
-          <SettingsIcon aria-hidden="true" />
-        </UnStyledButton>
-      </Tooltip>
+    <>
+      <ActivityRail
+        onPluginToggle={handlePluginToggle}
+        onSettingsClick={() => setShowDialog('settings')}
+      />
       <Dialog
         open={showDialog === 'short-keys'}
         onOpenChange={handleOpenShortKeysDialog}
@@ -217,7 +134,6 @@ export const Sidebar: FC<SidebarProps> = ({
             Short Keys
           </Dialog.Title>
           <VisuallyHidden>
-            {/* Fixes Warning: Missing `Description` or `aria-describedby={undefined}` for {DialogContent} */}
             <Dialog.Description>
               This modal provides a list of available keyboard shortcuts and
               their functions.
@@ -238,7 +154,6 @@ export const Sidebar: FC<SidebarProps> = ({
             Settings
           </Dialog.Title>
           <VisuallyHidden>
-            {/* Fixes Warning: Missing `Description` or `aria-describedby={undefined}` for {DialogContent} */}
             <Dialog.Description>
               This modal lets you adjust header persistence, interface theme,
               and clear local storage.
@@ -335,6 +250,6 @@ export const Sidebar: FC<SidebarProps> = ({
           </Button>
         </div>
       </Dialog>
-    </div>
+    </>
   );
 };
diff --git a/packages/graphiql/src/ui/index.ts b/packages/graphiql/src/ui/index.ts
index ee953edb0b4..44a71a06f13 100644
--- a/packages/graphiql/src/ui/index.ts
+++ b/packages/graphiql/src/ui/index.ts
@@ -1,5 +1,6 @@
+export { ActivityBar } from './activity-bar';
+export type { ActivityBarProps } from './activity-bar';
 export { GraphiQLFooter } from './footer';
 export { GraphiQLLogo } from './logo';
 export { ShortKeys } from './short-keys';
-export { Sidebar } from './sidebar';
 export { GraphiQLToolbar } from './toolbar';

From 4fa53a8d2f111d9a894c59a7b7c79de8c9089136 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 12:11:41 -0700
Subject: [PATCH 23/38] v6: Add `SidePanel` component (#4291)

## Summary

This PR adds a `SidePanel` that hosts the active plugin's content next
to the new activity rail. The panel renders nothing when no plugin is
active, and remains user-resizable via the existing drag handle.
Together with the activity rail change, it completes the left-side
navigation chrome for the v6 layout.

## Test plan

- [x] Open the [deploy
preview](https://deploy-preview-4291--graphiql-test.netlify.app). With
no plugin active, confirm the side panel area is collapsed and the
editor takes the full width.
- [x] Click a plugin icon in the activity rail; confirm the side panel
opens with that plugin's content.
- [x] Drag the divider between the panel and the editor; confirm the
panel resizes smoothly and the width persists when you switch between
plugins.
- [x] Click the active plugin's icon a second time; confirm the panel
closes.
- [x] Toggle dark/light theme via the settings dialog; confirm the panel
chrome reads from the active tokens.

Refs: graphql/graphiql#4219
---
 .changeset/side-panel.md                      |  5 ++
 .../graphiql-react/src/components/index.ts    |  2 +
 .../src/components/side-panel/index.css       | 13 +++
 .../src/components/side-panel/index.tsx       | 29 +++++++
 .../side-panel/side-panel.stories.tsx         | 86 +++++++++++++++++++
 .../components/side-panel/side-panel.test.tsx | 38 ++++++++
 packages/graphiql/src/GraphiQL.tsx            | 15 +---
 packages/graphiql/src/graphiql.css            |  9 +-
 8 files changed, 180 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/side-panel.md
 create mode 100644 packages/graphiql-react/src/components/side-panel/index.css
 create mode 100644 packages/graphiql-react/src/components/side-panel/index.tsx
 create mode 100644 packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/side-panel/side-panel.test.tsx

diff --git a/.changeset/side-panel.md b/.changeset/side-panel.md
new file mode 100644
index 00000000000..1bdbedf0aab
--- /dev/null
+++ b/.changeset/side-panel.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add `SidePanel` component that hosts the active plugin's content next to the activity rail. Default width 340px, resizable.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index dd4ace671cf..5e9363cc35f 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -33,5 +33,7 @@ export { TopBar, TopBarView } from './top-bar';
 export type { TopBarProps, TopBarViewProps } from './top-bar';
 export { StatusBar, StatusBarView } from './status-bar';
 export type { StatusBarProps, StatusBarViewProps } from './status-bar';
+export { SidePanel, SidePanelView } from './side-panel';
+export type { SidePanelViewProps } from './side-panel';
 export { ActivityRail } from './activity-rail';
 export type { ActivityRailProps } from './activity-rail';
diff --git a/packages/graphiql-react/src/components/side-panel/index.css b/packages/graphiql-react/src/components/side-panel/index.css
new file mode 100644
index 00000000000..1f3813be86c
--- /dev/null
+++ b/packages/graphiql-react/src/components/side-panel/index.css
@@ -0,0 +1,13 @@
+/*
+ * SidePanel fills its resize-controlled parent. The parent div (`.graphiql-plugin`)
+ * owns the flex/width; SidePanel just stretches to fill it and adds its own chrome.
+ */
+.graphiql-side-panel {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  background: oklch(var(--bg-canvas));
+  border-right: 1px solid oklch(var(--border-default));
+  overflow: auto;
+}
diff --git a/packages/graphiql-react/src/components/side-panel/index.tsx b/packages/graphiql-react/src/components/side-panel/index.tsx
new file mode 100644
index 00000000000..37481eb6cfd
--- /dev/null
+++ b/packages/graphiql-react/src/components/side-panel/index.tsx
@@ -0,0 +1,29 @@
+import type { ComponentType, FC } from 'react';
+import { useGraphiQL } from '../provider';
+import './index.css';
+
+type Plugin = {
+  title: string;
+  content: ComponentType;
+};
+
+export const SidePanel: FC = () => {
+  const visiblePlugin = useGraphiQL(state => state.visiblePlugin);
+  if (!visiblePlugin) {
+    return null;
+  }
+  return <SidePanelView plugin={visiblePlugin} />;
+};
+
+export type SidePanelViewProps = {
+  plugin: Plugin;
+};
+
+export const SidePanelView: FC<SidePanelViewProps> = ({ plugin }) => {
+  const Content = plugin.content;
+  return (
+    <aside className="graphiql-side-panel" aria-label={plugin.title}>
+      <Content />
+    </aside>
+  );
+};
diff --git a/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx b/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
new file mode 100644
index 00000000000..31134ccfb51
--- /dev/null
+++ b/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
@@ -0,0 +1,86 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect } from 'react';
+import { GraphiQLProvider, useGraphiQLActions } from '../provider';
+import { DocsIcon, HistoryIcon } from '../../icons';
+import { SidePanel } from './';
+
+const mockFetcher = () => ({ data: null });
+
+const DOCS_PLUGIN = {
+  title: 'Documentation Explorer',
+  icon: DocsIcon,
+  content: () => (
+    <div style={{ padding: 16 }}>
+      <p style={{ margin: 0, color: 'oklch(var(--fg-muted))' }}>
+        Documentation content
+      </p>
+    </div>
+  ),
+};
+
+const HISTORY_PLUGIN = {
+  title: 'History',
+  icon: HistoryIcon,
+  content: () => (
+    <div style={{ padding: 16 }}>
+      <p style={{ margin: 0, color: 'oklch(var(--fg-muted))' }}>
+        History content
+      </p>
+    </div>
+  ),
+};
+
+function ActivatePlugin({ title }: { title: string }) {
+  const { setVisiblePlugin } = useGraphiQLActions();
+  useEffect(() => {
+    setVisiblePlugin(title);
+  }, [setVisiblePlugin, title]);
+  return null;
+}
+
+const meta: Meta<typeof SidePanel> = {
+  title: 'Components/SidePanel',
+  component: SidePanel,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <GraphiQLProvider
+        fetcher={mockFetcher}
+        plugins={[DOCS_PLUGIN, HISTORY_PLUGIN]}
+      >
+        <Story />
+      </GraphiQLProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof SidePanel>;
+
+export const Hidden: Story = {
+  name: 'No active plugin (hidden)',
+};
+
+export const DocsPanel: Story = {
+  name: 'Documentation Explorer active',
+  decorators: [
+    Story => (
+      <>
+        <ActivatePlugin title="Documentation Explorer" />
+        <Story />
+      </>
+    ),
+  ],
+};
+
+export const HistoryPanel: Story = {
+  name: 'History active',
+  decorators: [
+    Story => (
+      <>
+        <ActivatePlugin title="History" />
+        <Story />
+      </>
+    ),
+  ],
+};
diff --git a/packages/graphiql-react/src/components/side-panel/side-panel.test.tsx b/packages/graphiql-react/src/components/side-panel/side-panel.test.tsx
new file mode 100644
index 00000000000..b45b5dc2683
--- /dev/null
+++ b/packages/graphiql-react/src/components/side-panel/side-panel.test.tsx
@@ -0,0 +1,38 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SidePanelView } from './';
+
+const MOCK_PLUGIN = {
+  title: 'Test Plugin',
+  content: () => <div>Plugin content</div>,
+};
+
+describe('SidePanelView', () => {
+  it('renders the plugin content inside the panel', () => {
+    render(<SidePanelView plugin={MOCK_PLUGIN} />);
+    expect(screen.getByText('Plugin content')).toBeInTheDocument();
+  });
+
+  it('renders as an aside element with aria-label matching the plugin title', () => {
+    const { container } = render(<SidePanelView plugin={MOCK_PLUGIN} />);
+    const aside = container.querySelector('aside.graphiql-side-panel');
+    expect(aside).not.toBeNull();
+    expect(aside).toHaveAttribute('aria-label', 'Test Plugin');
+  });
+
+  it('renders a different aria-label when the plugin title changes', () => {
+    const { container, rerender } = render(
+      <SidePanelView plugin={MOCK_PLUGIN} />,
+    );
+    rerender(
+      <SidePanelView
+        plugin={{ title: 'Other', content: () => <div>Other</div> }}
+      />,
+    );
+    expect(
+      container.querySelector('aside.graphiql-side-panel'),
+    ).toHaveAttribute('aria-label', 'Other');
+  });
+});
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index a9b09616dd0..d06c7c45705 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -20,6 +20,7 @@ import {
   PlusIcon,
   QueryEditor,
   ResponseEditor,
+  SidePanel,
   Spinner,
   StatusBar,
   Tab,
@@ -233,8 +234,6 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
   );
   const hasMonaco = useMonaco(state => Boolean(state.monaco));
 
-  const PluginContent = visiblePlugin?.content;
-
   const pluginResize = useDragResize({
     defaultSizeRelation: 1 / 3,
     direction: 'horizontal',
@@ -460,16 +459,8 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
             setHiddenElement={pluginResize.setHiddenElement}
           />
           <div className="graphiql-main">
-            <div
-              ref={pluginResize.firstRef}
-              className="graphiql-plugin"
-              style={{
-                // Make sure the container shrinks when containing long
-                // non-breaking texts
-                minWidth: '200px',
-              }}
-            >
-              {PluginContent && <PluginContent />}
+            <div ref={pluginResize.firstRef} className="graphiql-plugin">
+              <SidePanel />
             </div>
             {visiblePlugin && (
               <div
diff --git a/packages/graphiql/src/graphiql.css b/packages/graphiql/src/graphiql.css
index 8ea0d9ab560..647a951525e 100644
--- a/packages/graphiql/src/graphiql.css
+++ b/packages/graphiql/src/graphiql.css
@@ -191,13 +191,12 @@ button.graphiql-tab-add {
     hsla(var(--color-neutral), var(--alpha-background-heavy));
 }
 
-/* The plugin container */
+/* The plugin container — sizing controlled by useDragResize; chrome handled by <SidePanel> */
 .graphiql-container .graphiql-plugin {
-  border-left: 1px solid
-    hsla(var(--color-neutral), var(--alpha-background-heavy));
+  display: flex;
   flex: 1;
-  overflow-y: auto;
-  padding: var(--px-16);
+  min-width: 0;
+  overflow: hidden;
 }
 
 /* Generic drag bar for horizontal resizing */

From f5968fed097799df7105fb6e414603020f11bd18 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 14:15:24 -0700
Subject: [PATCH 24/38] v6: Restyle editor tabs with dirty state and close
 affordance (#4292)

## Summary

This PR restyles the editor tab strip for v6 and introduces dirty-state
and save affordances. Each tab now shows an accent dot when its query
differs from the last saved snapshot, and hovering a tab reveals a close
button. A new save action, bound to `Cmd-S` / `Ctrl-S`, snapshots the
active tab's query, and the right side of the strip gains prettify,
copy, and save buttons that surface the existing actions inline.

A note on save: today `saveQuery()` just updates the `lastSavedQuery`
snapshot to clear the dirty dot. Tab content already auto-persists to
localStorage, so save isn't writing anything new. The hook is in place
so collections (planned as a follow-up package) can give save real
semantics, snapshotting the active tab into the current collection
entry. Until that lands, the indicator is a cosmetic baseline.

## Test plan

- [x] Open the [deploy
preview](https://deploy-preview-4292--graphiql-test.netlify.app) with at
least two tabs. Edit the query in one tab and confirm the accent dot
appears next to its label.
- [x] Press `Cmd-S` (macOS) or `Ctrl-S` (Windows/Linux); confirm the dot
disappears.
- [x] Click the Save button in the tab strip's right-side action area;
confirm the dot also clears.
- [x] Hover over a dirty tab; confirm the close button appears and the
dirty dot shifts left so it doesn't overlap the close icon.
- [x] Close an inactive tab via the close button; confirm the active tab
stays active. Close the active tab; confirm focus moves to an adjacent
tab.
- [x] Drag tabs to reorder them; confirm the dirty state follows the
correct tab.
- [x] Tab through the strip with the keyboard; confirm both tab labels
and the right-side action buttons are reachable in a logical order.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-editortabs.md              |   5 +
 .../src/components/operation-editor.tsx       |   2 +
 .../src/components/tabs/index.css             |  22 ++-
 .../src/components/tabs/index.tsx             |  10 +-
 .../src/components/tabs/tabs.stories.tsx      |  39 +++++
 packages/graphiql-react/src/constants.ts      |  10 ++
 packages/graphiql-react/src/icons/index.tsx   |   2 +
 packages/graphiql-react/src/icons/save.svg    |   3 +
 .../graphiql-react/src/stores/editor.spec.ts  | 133 ++++++++++++++++++
 packages/graphiql-react/src/stores/editor.ts  |  21 +++
 .../graphiql-react/src/utility/tabs.spec.ts   |  20 +++
 packages/graphiql-react/src/utility/tabs.ts   |  20 ++-
 packages/graphiql/src/GraphiQL.tsx            |  59 +++++++-
 packages/graphiql/src/graphiql.css            |  26 ++++
 14 files changed, 363 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/restyle-editortabs.md
 create mode 100644 packages/graphiql-react/src/icons/save.svg
 create mode 100644 packages/graphiql-react/src/stores/editor.spec.ts

diff --git a/.changeset/restyle-editortabs.md b/.changeset/restyle-editortabs.md
new file mode 100644
index 00000000000..7e99f4f862e
--- /dev/null
+++ b/.changeset/restyle-editortabs.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Restyle the editor tabs to the v6 design. Tabs now show a dirty-state dot when unsaved changes are present and a hover-only close affordance per tab. Adds a `lastSavedQuery` field to the tab store; the dirty state is computed from the diff against that snapshot. Adds a `saveQuery` action (keybind `Ctrl-S` / `Cmd-S`) that updates the snapshot. Adds prettify, copy, and save buttons to the right side of the tab strip.
diff --git a/packages/graphiql-react/src/components/operation-editor.tsx b/packages/graphiql-react/src/components/operation-editor.tsx
index a34abfc8832..2fac9511507 100644
--- a/packages/graphiql-react/src/components/operation-editor.tsx
+++ b/packages/graphiql-react/src/components/operation-editor.tsx
@@ -56,6 +56,7 @@ export const OperationEditor: FC<OperationEditorProps> = ({
     copyQuery,
     prettifyEditors,
     mergeQuery,
+    saveQuery,
   } = useGraphiQLActions();
   const {
     initialQuery,
@@ -263,6 +264,7 @@ export const OperationEditor: FC<OperationEditorProps> = ({
       editor.addAction({ ...KEY_BINDINGS.copyQuery, run: copyQuery }),
       editor.addAction({ ...KEY_BINDINGS.prettify, run: prettifyEditors }),
       editor.addAction({ ...KEY_BINDINGS.mergeFragments, run: mergeQuery }),
+      editor.addAction({ ...KEY_BINDINGS.saveQuery, run: saveQuery }),
       editor,
       model,
     ];
diff --git a/packages/graphiql-react/src/components/tabs/index.css b/packages/graphiql-react/src/components/tabs/index.css
index dd75eec0abe..2209e2b2231 100644
--- a/packages/graphiql-react/src/components/tabs/index.css
+++ b/packages/graphiql-react/src/components/tabs/index.css
@@ -91,12 +91,30 @@
     line-height: 0;
 
     & > svg {
-      height: var(--px-8);
-      width: var(--px-8);
+      height: 10px;
+      width: 10px;
     }
 
     &:hover {
       color: oklch(var(--fg-default));
     }
   }
+
+  /* Dirty-state dot — 5×5 blue dot at top-right of the tab */
+  .graphiql-tab-dirty {
+    position: absolute;
+    top: 4px;
+    right: 4px;
+    width: 5px;
+    height: 5px;
+    border-radius: 50%;
+    background: oklch(var(--accent-blue));
+    pointer-events: none;
+  }
+
+  /* Shift dirty dot left when the close button is visible to avoid overlap */
+  &:hover .graphiql-tab-dirty,
+  &.graphiql-tab-active .graphiql-tab-dirty {
+    right: 20px;
+  }
 }
diff --git a/packages/graphiql-react/src/components/tabs/index.tsx b/packages/graphiql-react/src/components/tabs/index.tsx
index 7748e38ddad..39ab9db8b4d 100644
--- a/packages/graphiql-react/src/components/tabs/index.tsx
+++ b/packages/graphiql-react/src/components/tabs/index.tsx
@@ -7,10 +7,11 @@ import './index.css';
 
 interface TabProps extends ComponentPropsWithoutRef<typeof Reorder.Item> {
   isActive?: boolean;
+  isDirty?: boolean;
 }
 
 const TabRoot = forwardRef<HTMLLIElement, TabProps>(
-  ({ isActive, value, children, className, ...props }, ref) => (
+  ({ isActive, isDirty, value, children, className, ...props }, ref) => (
     <Reorder.Item
       {...props}
       ref={ref}
@@ -25,6 +26,13 @@ const TabRoot = forwardRef<HTMLLIElement, TabProps>(
       )}
     >
       {children}
+      {isDirty && (
+        <span
+          className="graphiql-tab-dirty"
+          aria-label="Unsaved changes"
+          role="status"
+        />
+      )}
     </Reorder.Item>
   ),
 );
diff --git a/packages/graphiql-react/src/components/tabs/tabs.stories.tsx b/packages/graphiql-react/src/components/tabs/tabs.stories.tsx
index b02614db231..d917e625d56 100644
--- a/packages/graphiql-react/src/components/tabs/tabs.stories.tsx
+++ b/packages/graphiql-react/src/components/tabs/tabs.stories.tsx
@@ -95,3 +95,42 @@ export const ActiveState: Story = {
     );
   },
 };
+
+export const DirtyState: Story = {
+  render: function DirtyStateStory() {
+    const [tabs] = useState([
+      { id: 'a', label: 'GetUser' },
+      { id: 'b', label: 'ListPosts' },
+    ]);
+    const [active, setActive] = useState('a');
+
+    return (
+      <div>
+        <Tabs values={tabs} onReorder={() => {}} className="no-scrollbar">
+          {tabs.map((tab, i) => (
+            <Tab
+              key={tab.id}
+              value={tab}
+              isActive={active === tab.id}
+              isDirty={i === 0}
+            >
+              <Tab.Button onClick={() => setActive(tab.id)}>
+                {tab.label}
+              </Tab.Button>
+              <Tab.Close />
+            </Tab>
+          ))}
+        </Tabs>
+        <div
+          style={{
+            padding: '12px',
+            color: 'oklch(var(--fg-subtle))',
+            fontSize: '11px',
+          }}
+        >
+          First tab has unsaved edits (dirty dot visible).
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/constants.ts b/packages/graphiql-react/src/constants.ts
index 18b8c25fb8c..dfe03495f89 100644
--- a/packages/graphiql-react/src/constants.ts
+++ b/packages/graphiql-react/src/constants.ts
@@ -31,6 +31,10 @@ export const KEY_MAP = Object.freeze({
     key: 'Shift-Ctrl-C',
     keybindings: [KeyMod.Shift | KeyMod.WinCtrl | KeyCode.KeyC],
   },
+  saveQuery: {
+    key: 'Ctrl-S',
+    keybindings: [KeyMod.CtrlCmd | KeyCode.KeyS],
+  },
   refetchSchema: {
     key: 'Shift-Ctrl-R',
   },
@@ -110,6 +114,12 @@ export const KEY_BINDINGS = {
     contextMenuGroupId: 'graphql',
     keybindings: KEY_MAP.copyQuery.keybindings,
   },
+  saveQuery: {
+    id: 'graphql-save',
+    label: 'Save Query',
+    contextMenuGroupId: 'graphql',
+    keybindings: KEY_MAP.saveQuery.keybindings,
+  },
 } as const;
 
 export const URI_NAME = {
diff --git a/packages/graphiql-react/src/icons/index.tsx b/packages/graphiql-react/src/icons/index.tsx
index 29a8f538b6f..84b7b3ca143 100644
--- a/packages/graphiql-react/src/icons/index.tsx
+++ b/packages/graphiql-react/src/icons/index.tsx
@@ -25,6 +25,7 @@ import _PlusIcon from './plus.svg?react';
 import _PrettifyIcon from './prettify.svg?react';
 import _ReloadIcon from './reload.svg?react';
 import _RootTypeIcon from './root-type.svg?react';
+import _SaveIcon from './save.svg?react';
 import _SettingsIcon from './settings.svg?react';
 import _StarFilledIcon from './star-filled.svg?react';
 import _StarIcon from './star.svg?react';
@@ -57,6 +58,7 @@ export const PlusIcon = generateIcon(_PlusIcon);
 export const PrettifyIcon = generateIcon(_PrettifyIcon);
 export const ReloadIcon = generateIcon(_ReloadIcon);
 export const RootTypeIcon = generateIcon(_RootTypeIcon);
+export const SaveIcon = generateIcon(_SaveIcon);
 export const SettingsIcon = generateIcon(_SettingsIcon);
 export const StarFilledIcon = generateIcon(_StarFilledIcon);
 export const StarIcon = generateIcon(_StarIcon);
diff --git a/packages/graphiql-react/src/icons/save.svg b/packages/graphiql-react/src/icons/save.svg
new file mode 100644
index 00000000000..51777550234
--- /dev/null
+++ b/packages/graphiql-react/src/icons/save.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="currentColor" viewBox="0 0 16 16">
+  <path d="M11.5 2H3a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1V4.5zM8 12a2 2 0 1 1 0-4 2 2 0 0 1 0 4m2-7H4V3h6z"/>
+</svg>
diff --git a/packages/graphiql-react/src/stores/editor.spec.ts b/packages/graphiql-react/src/stores/editor.spec.ts
new file mode 100644
index 00000000000..8efc9d024a9
--- /dev/null
+++ b/packages/graphiql-react/src/stores/editor.spec.ts
@@ -0,0 +1,133 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { create } from 'zustand';
+import { StorageAPI } from '@graphiql/toolkit';
+import { createEditorSlice } from './editor';
+import { createStorageSlice } from './storage';
+import { createTab } from '../utility/tabs';
+import type { SlicesWithActions } from '../types';
+
+function makeStore(overrides: Record<string, unknown> = {}) {
+  const storage = new StorageAPI();
+  const tab = createTab({ query: 'query Foo {}' });
+
+  const store = create<SlicesWithActions>((...args) => {
+    const storageSlice = createStorageSlice({ storage })(...args);
+    const editorSlice = createEditorSlice({
+      activeTabIndex: 0,
+      defaultHeaders: undefined,
+      defaultQuery: '',
+      externalFragments: new Map(),
+      initialHeaders: '',
+      initialQuery: '',
+      initialVariables: '',
+      onCopyQuery: undefined,
+      onEditOperationName: undefined,
+      onPrettifyQuery: async q => q,
+      onTabChange: undefined,
+      shouldPersistHeaders: false,
+      tabs: [tab],
+      uriInstanceId: 'test-',
+      ...overrides,
+    })(...args);
+
+    return {
+      ...storageSlice,
+      ...editorSlice,
+      // Stub out the slices/actions that aren't under test.
+      actions: {
+        ...editorSlice.actions,
+        stop: vi.fn(),
+        run: vi.fn(),
+        setPlugins: vi.fn(),
+        setVisiblePlugin: vi.fn(),
+        setSchemaReference: vi.fn(),
+        refetchSchema: vi.fn(),
+        setTheme: vi.fn(),
+        toggleTheme: vi.fn(),
+      } as any,
+    } as SlicesWithActions;
+  });
+
+  return store;
+}
+
+describe('tab management', () => {
+  it('addTab adds a new tab', () => {
+    const store = makeStore();
+    expect(store.getState().tabs).toHaveLength(1);
+    store.getState().actions.addTab();
+    expect(store.getState().tabs).toHaveLength(2);
+  });
+
+  it('addTab activates the new tab', () => {
+    const store = makeStore();
+    store.getState().actions.addTab();
+    expect(store.getState().activeTabIndex).toBe(1);
+  });
+
+  it('closeTab removes the tab at the given index', () => {
+    const store = makeStore();
+    store.getState().actions.addTab();
+    expect(store.getState().tabs).toHaveLength(2);
+    store.getState().actions.closeTab(1);
+    expect(store.getState().tabs).toHaveLength(1);
+  });
+
+  it('closing the active tab activates the previous tab', () => {
+    const store = makeStore();
+    store.getState().actions.addTab();
+    expect(store.getState().activeTabIndex).toBe(1);
+    store.getState().actions.closeTab(1);
+    expect(store.getState().activeTabIndex).toBe(0);
+  });
+});
+
+describe('dirty state', () => {
+  it('a new tab has lastSavedQuery null', () => {
+    const store = makeStore();
+    const tab = store.getState().tabs[0]!;
+    expect(tab.lastSavedQuery).toBeNull();
+  });
+
+  it('tab is dirty when query differs from lastSavedQuery', () => {
+    const store = makeStore();
+    const tab = store.getState().tabs[0]!;
+    expect(tab.query).not.toBe(tab.lastSavedQuery);
+  });
+
+  it('saveQuery sets lastSavedQuery on the active tab', () => {
+    const store = makeStore();
+    // With no Monaco editor in tests, queryEditor is undefined, so
+    // saveQuery sets lastSavedQuery to null.
+    store.getState().actions.saveQuery();
+    const tab = store.getState().tabs[0]!;
+    expect(tab.lastSavedQuery).toBeNull();
+  });
+
+  it('updateActiveTabValues does not touch lastSavedQuery', () => {
+    const store = makeStore();
+    store.getState().actions.updateActiveTabValues({ query: 'query Bar {}' });
+    const tab = store.getState().tabs[0]!;
+    expect(tab.lastSavedQuery).toBeNull();
+    expect(tab.query).toBe('query Bar {}');
+  });
+
+  it('saveQuery is independent of run/execute', () => {
+    const store = makeStore();
+    // Editing the query (simulated via updateActiveTabValues) does NOT clear dirty.
+    store
+      .getState()
+      .actions.updateActiveTabValues({ query: 'query Updated {}' });
+    const tabAfterEdit = store.getState().tabs[0]!;
+    expect(tabAfterEdit.lastSavedQuery).toBeNull();
+    expect(tabAfterEdit.query).toBe('query Updated {}');
+
+    // saveQuery clears dirty.
+    store.getState().actions.saveQuery();
+    const tabAfterSave = store.getState().tabs[0]!;
+    // lastSavedQuery is set to what the Monaco editor returns (null without Monaco).
+    expect(tabAfterSave.lastSavedQuery).toBeNull();
+  });
+});
diff --git a/packages/graphiql-react/src/stores/editor.ts b/packages/graphiql-react/src/stores/editor.ts
index 3d9c03dbd98..5c7c4830e5b 100644
--- a/packages/graphiql-react/src/stores/editor.ts
+++ b/packages/graphiql-react/src/stores/editor.ts
@@ -213,6 +213,12 @@ export interface EditorActions {
     operations?: OperationDefinitionNode[];
   }): void;
 
+  /**
+   * Save the current query. Updates `lastSavedQuery` on the active tab so the
+   * dirty-state dot clears. Triggered by the Save toolbar button or ⌘S.
+   */
+  saveQuery(): void;
+
   /**
    * Copy a query to clipboard.
    */
@@ -459,6 +465,21 @@ export const createEditorSlice: CreateEditorSlice = initial => (set, get) => {
         operations,
       });
     },
+    saveQuery() {
+      const { queryEditor } = get();
+      const query = queryEditor?.getValue() ?? null;
+      set(({ activeTabIndex, tabs, onTabChange, actions }) => {
+        const updated = {
+          tabs: tabs.map((tab, i) =>
+            i === activeTabIndex ? { ...tab, lastSavedQuery: query } : tab,
+          ),
+          activeTabIndex,
+        };
+        actions.storeTabs(updated);
+        onTabChange?.(updated);
+        return updated;
+      });
+    },
     async copyQuery() {
       const { queryEditor, onCopyQuery } = get();
       if (!queryEditor) {
diff --git a/packages/graphiql-react/src/utility/tabs.spec.ts b/packages/graphiql-react/src/utility/tabs.spec.ts
index 82baff6dc1e..f90cffd6a03 100644
--- a/packages/graphiql-react/src/utility/tabs.spec.ts
+++ b/packages/graphiql-react/src/utility/tabs.spec.ts
@@ -5,6 +5,7 @@ import {
   fuzzyExtractOperationName,
   getDefaultTabState,
   clearHeadersFromTabs,
+  serializeTabState,
 } from './tabs';
 import { STORAGE_KEY } from '../constants';
 
@@ -28,6 +29,25 @@ describe('createTab', () => {
       }),
     );
   });
+
+  it('initializes lastSavedQuery to null', () => {
+    expect(createTab({ query: 'query Foo {}' })).toEqual(
+      expect.objectContaining({ lastSavedQuery: null }),
+    );
+  });
+});
+
+describe('serializeTabState', () => {
+  it('nullifies lastSavedQuery in serialized output (not persisted)', () => {
+    const tab = {
+      ...createTab({ query: 'query Foo {}' }),
+      lastSavedQuery: 'query Foo {}',
+    };
+    const state = { tabs: [tab], activeTabIndex: 0 };
+    const parsed = JSON.parse(serializeTabState(state));
+    // lastSavedQuery is serialized as null so the field is reset on reload
+    expect(parsed.tabs[0].lastSavedQuery).toBeNull();
+  });
 });
 
 describe('fuzzyExtractionOperationTitle', () => {
diff --git a/packages/graphiql-react/src/utility/tabs.ts b/packages/graphiql-react/src/utility/tabs.ts
index 6eccfea88cc..7fa436c5a47 100644
--- a/packages/graphiql-react/src/utility/tabs.ts
+++ b/packages/graphiql-react/src/utility/tabs.ts
@@ -48,6 +48,14 @@ export interface TabState extends TabDefinition {
    * The contents of the response editor of this tab.
    */
   response: string | null;
+
+  /**
+   * The query text at the point of the last explicit save (toolbar Save button
+   * or ⌘S). Used to derive the tab dirty state: a tab is dirty when
+   * `query !== lastSavedQuery`. `null` means the tab has never been explicitly
+   * saved.
+   */
+  lastSavedQuery: string | null;
 }
 
 /**
@@ -132,10 +140,18 @@ export function getDefaultTabState({
           headers,
           operationName,
           response: null,
+          lastSavedQuery: null,
         });
         parsed.activeTabIndex = parsed.tabs.length - 1;
       }
 
+      // Tabs loaded from storage won't have lastSavedQuery — initialize it.
+      parsed.tabs = parsed.tabs.map(tab =>
+        'lastSavedQuery' in (tab as object)
+          ? tab
+          : { ...tab, lastSavedQuery: null },
+      );
+
       return parsed;
     }
     throw new Error('Storage for tabs is invalid');
@@ -160,7 +176,7 @@ function isTabsState(obj: any): obj is TabsState {
 }
 
 function isTabState(obj: any): obj is TabState {
-  // We don't persist the hash, so we skip the check here
+  // We don't persist hash or lastSavedQuery, so skip those checks here.
   return (
     obj &&
     typeof obj === 'object' &&
@@ -194,6 +210,7 @@ export function serializeTabState(
   return JSON.stringify(tabState, (key, value) =>
     key === 'hash' ||
     key === 'response' ||
+    key === 'lastSavedQuery' ||
     (!shouldPersistHeaders && key === 'headers')
       ? null
       : value,
@@ -215,6 +232,7 @@ export function createTab({
     headers,
     operationName,
     response: null,
+    lastSavedQuery: null,
   };
 }
 
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index d06c7c45705..14ffd0b134a 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -14,19 +14,22 @@ import { useState, Children, useRef, Fragment } from 'react';
 import {
   ChevronDownIcon,
   ChevronUpIcon,
+  CopyIcon,
   ExecuteButton,
   GraphiQLProvider,
   HeaderEditor,
   PlusIcon,
+  PrettifyIcon,
   QueryEditor,
   ResponseEditor,
+  SaveIcon,
   SidePanel,
   Spinner,
-  StatusBar,
   Tab,
   Tabs,
   Tooltip,
   TopBar,
+  StatusBar,
   UnStyledButton,
   useDragResize,
   useGraphiQL,
@@ -198,6 +201,9 @@ type ButtonHandler = MouseEventHandler<HTMLButtonElement>;
 
 const LABEL = {
   newTab: 'New tab',
+  prettify: 'Prettify query',
+  copy: 'Copy query',
+  save: 'Save query',
 };
 
 export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
@@ -213,8 +219,16 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
   responseTooltip,
   showPersistHeadersSettings,
 }) => {
-  const { addTab, moveTab, closeTab, changeTab, setVisiblePlugin } =
-    useGraphiQLActions();
+  const {
+    addTab,
+    moveTab,
+    closeTab,
+    changeTab,
+    setVisiblePlugin,
+    saveQuery,
+    copyQuery,
+    prettifyEditors,
+  } = useGraphiQLActions();
   const {
     initialVariables,
     initialHeaders,
@@ -477,13 +491,14 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
                   aria-label="Select active operation"
                   className="no-scrollbar"
                 >
-                  {tabs.map((tab, index, arr) => (
+                  {tabs.map((tab, index) => (
                     <Tab
                       key={tab.id}
                       // Prevent overscroll over container
                       dragConstraints={tabContainerRef}
                       value={tab}
                       isActive={index === activeTabIndex}
+                      isDirty={tab.query !== tab.lastSavedQuery}
                     >
                       <Tab.Button
                         aria-controls="graphiql-session"
@@ -493,7 +508,9 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
                       >
                         {tab.title}
                       </Tab.Button>
-                      {arr.length > 1 && <Tab.Close onClick={handleTabClose} />}
+                      {tabs.length > 1 && (
+                        <Tab.Close onClick={handleTabClose} />
+                      )}
                     </Tab>
                   ))}
                 </Tabs>
@@ -507,6 +524,38 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
                     <PlusIcon aria-hidden="true" />
                   </UnStyledButton>
                 </Tooltip>
+                <div className="graphiql-tab-strip-actions">
+                  <Tooltip label={LABEL.prettify}>
+                    <UnStyledButton
+                      type="button"
+                      className="graphiql-tab-strip-action"
+                      onClick={prettifyEditors}
+                      aria-label={LABEL.prettify}
+                    >
+                      <PrettifyIcon aria-hidden="true" />
+                    </UnStyledButton>
+                  </Tooltip>
+                  <Tooltip label={LABEL.copy}>
+                    <UnStyledButton
+                      type="button"
+                      className="graphiql-tab-strip-action"
+                      onClick={copyQuery}
+                      aria-label={LABEL.copy}
+                    >
+                      <CopyIcon aria-hidden="true" />
+                    </UnStyledButton>
+                  </Tooltip>
+                  <Tooltip label={LABEL.save}>
+                    <UnStyledButton
+                      type="button"
+                      className="graphiql-tab-strip-action"
+                      onClick={saveQuery}
+                      aria-label={LABEL.save}
+                    >
+                      <SaveIcon aria-hidden="true" />
+                    </UnStyledButton>
+                  </Tooltip>
+                </div>
                 {logo}
               </div>
               <div
diff --git a/packages/graphiql/src/graphiql.css b/packages/graphiql/src/graphiql.css
index 647a951525e..328772b2991 100644
--- a/packages/graphiql/src/graphiql.css
+++ b/packages/graphiql/src/graphiql.css
@@ -59,6 +59,32 @@ button.graphiql-tab-add {
   }
 }
 
+/* Right-side tab strip action buttons (prettify, copy, save) */
+.graphiql-tab-strip-actions {
+  display: flex;
+  align-items: center;
+  margin-left: auto;
+  gap: 0;
+}
+
+button.graphiql-tab-strip-action {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--px-4);
+  color: oklch(var(--fg-subtle));
+
+  & > svg {
+    display: block;
+    height: 13px;
+    width: 13px;
+  }
+
+  &:hover {
+    color: oklch(var(--fg-default));
+  }
+}
+
 /* The GraphiQL logo */
 .graphiql-container .graphiql-logo {
   margin-left: auto;

From 7c9adc5e67b8cd7bf32f9c555a18eb9caa4f0ef0 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 16:38:13 -0700
Subject: [PATCH 25/38] yarn dedupe

---
 yarn.lock | 84 ++++++-------------------------------------------------
 1 file changed, 8 insertions(+), 76 deletions(-)

diff --git a/yarn.lock b/yarn.lock
index 15d6bd6574e..b903403a4b3 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -6770,22 +6770,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@testing-library/jest-dom@npm:^6.6.3":
-  version: 6.6.3
-  resolution: "@testing-library/jest-dom@npm:6.6.3"
-  dependencies:
-    "@adobe/css-tools": "npm:^4.4.0"
-    aria-query: "npm:^5.0.0"
-    chalk: "npm:^3.0.0"
-    css.escape: "npm:^1.5.1"
-    dom-accessibility-api: "npm:^0.6.3"
-    lodash: "npm:^4.17.21"
-    redent: "npm:^3.0.0"
-  checksum: 10c0/5566b6c0b7b0709bc244aec3aa3dc9e5f4663e8fb2b99d8cd456fc07279e59db6076cbf798f9d3099a98fca7ef4cd50e4e1f4c4dec5a60a8fad8d24a638a5bf6
-  languageName: node
-  linkType: hard
-
-"@testing-library/jest-dom@npm:^6.9.1":
+"@testing-library/jest-dom@npm:^6.6.3, @testing-library/jest-dom@npm:^6.9.1":
   version: 6.9.1
   resolution: "@testing-library/jest-dom@npm:6.9.1"
   dependencies:
@@ -6883,16 +6868,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/babel__traverse@npm:*":
-  version: 7.20.1
-  resolution: "@types/babel__traverse@npm:7.20.1"
-  dependencies:
-    "@babel/types": "npm:^7.20.7"
-  checksum: 10c0/5a6a3a26be090573309527184a31f1b82ef55f3d73d811c15f181d323e471305f2390651a04d49d4cd4ca41bbeabb53c9f7862a8e09eab5a0f8910a6aec6e867
-  languageName: node
-  linkType: hard
-
-"@types/babel__traverse@npm:^7.20.7":
+"@types/babel__traverse@npm:*, @types/babel__traverse@npm:^7.20.7":
   version: 7.28.0
   resolution: "@types/babel__traverse@npm:7.28.0"
   dependencies:
@@ -9755,16 +9731,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chalk@npm:^3.0.0":
-  version: 3.0.0
-  resolution: "chalk@npm:3.0.0"
-  dependencies:
-    ansi-styles: "npm:^4.1.0"
-    supports-color: "npm:^7.1.0"
-  checksum: 10c0/ee650b0a065b3d7a6fda258e75d3a86fc8e4effa55871da730a9e42ccb035bf5fd203525e5a1ef45ec2582ecc4f65b47eb11357c526b84dd29a14fb162c414d2
-  languageName: node
-  linkType: hard
-
 "chalk@npm:^4.0.2, chalk@npm:^4.1.0, chalk@npm:^4.1.2":
   version: 4.1.2
   resolution: "chalk@npm:4.1.2"
@@ -17022,14 +16988,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2":
-  version: 7.1.2
-  resolution: "minipass@npm:7.1.2"
-  checksum: 10c0/b0fd20bb9fb56e5fa9a8bfac539e8915ae07430a619e4b86ff71f5fc757ef3924b23b2c4230393af1eda647ed3d75739e4e0acb250a6b1eb277cf7f8fe449557
-  languageName: node
-  linkType: hard
-
-"minipass@npm:^7.1.3":
+"minipass@npm:^5.0.0 || ^6.0.2 || ^7.0.0, minipass@npm:^7.0.2, minipass@npm:^7.0.3, minipass@npm:^7.0.4, minipass@npm:^7.1.2, minipass@npm:^7.1.3":
   version: 7.1.3
   resolution: "minipass@npm:7.1.3"
   checksum: 10c0/539da88daca16533211ea5a9ee98dc62ff5742f531f54640dd34429e621955e91cc280a91a776026264b7f9f6735947629f920944e9c1558369e8bf22eb33fbb
@@ -17793,19 +17752,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"open@npm:^10.0.3":
-  version: 10.1.2
-  resolution: "open@npm:10.1.2"
-  dependencies:
-    default-browser: "npm:^5.2.1"
-    define-lazy-prop: "npm:^3.0.0"
-    is-inside-container: "npm:^1.0.0"
-    is-wsl: "npm:^3.1.0"
-  checksum: 10c0/1bee796f06e549ce764f693272100323fbc04da8fa3c5b0402d6c2d11b3d76fa0aac0be7535e710015ff035326638e3b9a563f3b0e7ac3266473ed5663caae6d
-  languageName: node
-  linkType: hard
-
-"open@npm:^10.2.0":
+"open@npm:^10.0.3, open@npm:^10.2.0":
   version: 10.2.0
   resolution: "open@npm:10.2.0"
   dependencies:
@@ -24092,9 +24039,9 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ws@npm:>=8.7.0, ws@npm:^8.18.0, ws@npm:^8.18.3, ws@npm:^8.20.0":
-  version: 8.20.0
-  resolution: "ws@npm:8.20.0"
+"ws@npm:>=8.7.0, ws@npm:^8.18.0, ws@npm:^8.18.3, ws@npm:^8.19.0, ws@npm:^8.20.0":
+  version: 8.20.1
+  resolution: "ws@npm:8.20.1"
   peerDependencies:
     bufferutil: ^4.0.1
     utf-8-validate: ">=5.0.2"
@@ -24103,7 +24050,7 @@ __metadata:
       optional: true
     utf-8-validate:
       optional: true
-  checksum: 10c0/956ac5f11738c914089b65878b9223692ace77337ba55379ae68e1ecbeae9b47a0c6eb9403688f609999a58c80d83d99865fe0029b229d308b08c1ef93d4ea14
+  checksum: 10c0/ce162433218399cdedeb76fd33363d4d86a7d910058d4e3c679dce08cea65d6da6b39f11baa4d7808d024cf46ed88f6a05c17611621aaad8fc5e62edacc30c5d
   languageName: node
   linkType: hard
 
@@ -24131,21 +24078,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ws@npm:^8.19.0":
-  version: 8.20.1
-  resolution: "ws@npm:8.20.1"
-  peerDependencies:
-    bufferutil: ^4.0.1
-    utf-8-validate: ">=5.0.2"
-  peerDependenciesMeta:
-    bufferutil:
-      optional: true
-    utf-8-validate:
-      optional: true
-  checksum: 10c0/ce162433218399cdedeb76fd33363d4d86a7d910058d4e3c679dce08cea65d6da6b39f11baa4d7808d024cf46ed88f6a05c17611621aaad8fc5e62edacc30c5d
-  languageName: node
-  linkType: hard
-
 "wsl-utils@npm:^0.1.0":
   version: 0.1.0
   resolution: "wsl-utils@npm:0.1.0"

From 92567d51050cad11501c679bae0c9377098345cd Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 16:53:02 -0700
Subject: [PATCH 26/38] v6: Restyle doc-explorer to v6 design tokens (#4294)

## Summary

- Migrate `@graphiql/plugin-doc-explorer` CSS from v5 HSL tokens to v6
OKLCH tokens.
- Use `PanelHeader` for the panel header.
- Type names: `--accent-orange`. Field and enum names:
`--accent-green-light`. Argument names: `--accent-purple`.

## Test plan

- [x] Open the Docs panel in the example app; confirm type/field colors
match the v6 palette and navigation (back button, search) still works.
- [x] Check the `DocExplorer` Storybook stories: schema overview, type
detail variants (object, enum, input), field detail, and token colors
story.
- [x] Verify the search overlay still expands over the header title
(focus the search icon while on a nested type page).

Refs: graphql/graphiql#4219
---
 .changeset/restyle-doc-explorer.md            |   5 +
 .../.storybook/main.ts                        |   9 +
 .../.storybook/preview.tsx                    |  52 ++++
 .../graphiql-plugin-doc-explorer/package.json |   6 +
 .../src/components/argument.css               |   8 +-
 .../src/components/default-value.css          |   2 +-
 .../src/components/deprecation-reason.css     |   6 +-
 .../src/components/directive.css              |   2 +-
 .../src/components/doc-explorer.css           |  64 ++---
 .../src/components/doc-explorer.tsx           |  50 ++--
 .../src/components/field-link.css             |   4 +-
 .../src/components/schema-documentation.css   |   2 +-
 .../src/components/search.css                 |  55 ++--
 .../src/components/type-documentation.css     |   2 +-
 .../src/components/type-link.css              |   4 +-
 .../src/stories/doc-explorer.stories.tsx      | 245 ++++++++++++++++++
 yarn.lock                                     |   4 +
 17 files changed, 429 insertions(+), 91 deletions(-)
 create mode 100644 .changeset/restyle-doc-explorer.md
 create mode 100644 packages/graphiql-plugin-doc-explorer/.storybook/main.ts
 create mode 100644 packages/graphiql-plugin-doc-explorer/.storybook/preview.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx

diff --git a/.changeset/restyle-doc-explorer.md b/.changeset/restyle-doc-explorer.md
new file mode 100644
index 00000000000..7affd764f3f
--- /dev/null
+++ b/.changeset/restyle-doc-explorer.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/plugin-doc-explorer': patch
+---
+
+Restyle to the v6 design. Uses the new `PanelHeader` chrome and OKLCH design tokens. Type names render in `--accent-orange`, field and enum names in `--accent-green-light`, argument names in `--accent-purple`.
diff --git a/packages/graphiql-plugin-doc-explorer/.storybook/main.ts b/packages/graphiql-plugin-doc-explorer/.storybook/main.ts
new file mode 100644
index 00000000000..dddd2d457b7
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/.storybook/main.ts
@@ -0,0 +1,9 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
+  framework: { name: '@storybook/react-vite', options: {} },
+};
+
+export default config;
diff --git a/packages/graphiql-plugin-doc-explorer/.storybook/preview.tsx b/packages/graphiql-plugin-doc-explorer/.storybook/preview.tsx
new file mode 100644
index 00000000000..6d1e00e82ee
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/.storybook/preview.tsx
@@ -0,0 +1,52 @@
+import { useEffect } from 'react';
+import type { Preview } from '@storybook/react-vite';
+import '@graphiql/react/style.css';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: { disable: true },
+    a11y: { test: 'error' },
+  },
+  globalTypes: {
+    theme: {
+      description: 'Theme',
+      defaultValue: 'dark',
+      toolbar: {
+        icon: 'circlehollow',
+        items: [
+          { value: 'dark', title: 'Dark' },
+          { value: 'light', title: 'Light' },
+        ],
+        dynamicTitle: true,
+      },
+    },
+  },
+  decorators: [
+    (Story, ctx) => {
+      useEffect(() => {
+        const root = document.documentElement;
+        root.setAttribute('data-theme', ctx.globals.theme);
+        document.body.style.background = 'oklch(var(--bg-canvas))';
+        document.body.style.color = 'oklch(var(--fg-default))';
+        document.body.style.margin = '0';
+      }, [ctx.globals.theme]);
+
+      return (
+        <div
+          className="graphiql-container"
+          style={{
+            padding: 24,
+            background: 'oklch(var(--bg-canvas))',
+            color: 'oklch(var(--fg-default))',
+            minHeight: '100vh',
+            boxSizing: 'border-box',
+          }}
+        >
+          <Story />
+        </div>
+      );
+    },
+  ],
+};
+
+export default preview;
diff --git a/packages/graphiql-plugin-doc-explorer/package.json b/packages/graphiql-plugin-doc-explorer/package.json
index 35535291ff6..24571da8d11 100644
--- a/packages/graphiql-plugin-doc-explorer/package.json
+++ b/packages/graphiql-plugin-doc-explorer/package.json
@@ -35,6 +35,8 @@
     "types:check": "tsgo --noEmit",
     "dev": "vite build --watch --emptyOutDir=false",
     "build": "vite build",
+    "build-storybook": "storybook build",
+    "storybook": "storybook dev -p 6007",
     "test": "vitest run"
   },
   "peerDependencies": {
@@ -50,6 +52,9 @@
   },
   "devDependencies": {
     "@graphiql/react": "^0.37.4",
+    "@storybook/addon-a11y": "^10.3.6",
+    "@storybook/addon-vitest": "^10.3.6",
+    "@storybook/react-vite": "^10.3.6",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
@@ -58,6 +63,7 @@
     "graphql": "^16.9.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
+    "storybook": "^10.3.6",
     "vite": "^6.3.4",
     "vite-plugin-dts": "^4.5.3"
   }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/argument.css b/packages/graphiql-plugin-doc-explorer/src/components/argument.css
index 56cc073dd0c..7c80a917428 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/argument.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/argument.css
@@ -5,14 +5,14 @@
 }
 
 .graphiql-doc-explorer-argument-name {
-  color: hsl(var(--color-secondary));
+  color: oklch(var(--accent-purple));
 }
 
 .graphiql-doc-explorer-argument-deprecation {
-  background-color: hsla(var(--color-warning), var(--alpha-background-light));
-  border: 1px solid hsl(var(--color-warning));
+  background-color: oklch(var(--accent-orange) / 0.1);
+  border: 1px solid oklch(var(--accent-orange));
   border-radius: var(--border-radius-4);
-  color: hsl(var(--color-warning));
+  color: oklch(var(--accent-orange));
   padding: var(--px-8);
 }
 
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/default-value.css b/packages/graphiql-plugin-doc-explorer/src/components/default-value.css
index 59c2dcf2454..c6b18307640 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/default-value.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/default-value.css
@@ -1,3 +1,3 @@
 .graphiql-doc-explorer-default-value {
-  color: hsl(var(--color-success));
+  color: oklch(var(--accent-green));
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/deprecation-reason.css b/packages/graphiql-plugin-doc-explorer/src/components/deprecation-reason.css
index 123929af72d..32fe94a6d39 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/deprecation-reason.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/deprecation-reason.css
@@ -1,8 +1,8 @@
 .graphiql-doc-explorer-deprecation {
-  background-color: hsla(var(--color-warning), var(--alpha-background-light));
-  border: 1px solid hsl(var(--color-warning));
+  background-color: oklch(var(--accent-orange) / 0.1);
+  border: 1px solid oklch(var(--accent-orange));
   border-radius: var(--px-4);
-  color: hsl(var(--color-warning));
+  color: oklch(var(--accent-orange));
   padding: var(--px-8);
 }
 
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/directive.css b/packages/graphiql-plugin-doc-explorer/src/components/directive.css
index 17783cac86b..07c110f84f4 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/directive.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/directive.css
@@ -1,3 +1,3 @@
 .graphiql-doc-explorer-directive {
-  color: hsl(var(--color-secondary));
+  color: oklch(var(--accent-purple));
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
index 88178fa122d..5b27c40e27b 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
@@ -1,25 +1,26 @@
-/* The header of the doc explorer */
+/* The header wrapper — positions PanelHeader as a containing block for search overlay */
 .graphiql-doc-explorer-header {
-  display: flex;
-  justify-content: space-between;
-  position: relative;
+  & .graphiql-panel-header {
+    position: relative;
 
-  &:focus-within {
-    & .graphiql-doc-explorer-title {
-      /* Hide the header when focussing the search input */
-      visibility: hidden;
-    }
+    &:focus-within {
+      & .graphiql-doc-explorer-title {
+        /* Hide the title when the search input is focused */
+        visibility: hidden;
+      }
 
-    & .graphiql-doc-explorer-back:not(:focus) {
-      /**
-        * Make the back link invisible when focussing the search input. Hiding
-        * it in any other way makes it impossible to focus the link by pressing
-        * Shift-Tab while the input is focussed.
-        */
-      color: transparent;
+      & .graphiql-doc-explorer-back:not(:focus) {
+        /**
+          * Make the back link invisible when focussing the search input. Hiding
+          * it in any other way makes it impossible to focus the link by pressing
+          * Shift-Tab while the input is focussed.
+          */
+        color: transparent;
+      }
     }
   }
 }
+
 .graphiql-doc-explorer-header-content {
   display: flex;
   flex-direction: column;
@@ -29,11 +30,11 @@
 /* The search input in the header of the doc explorer */
 .graphiql-doc-explorer-search {
   position: absolute;
-  right: 0;
-  top: 0;
+  right: var(--px-14);
+  top: var(--px-10);
 
   &:focus-within {
-    left: 0;
+    left: var(--px-14);
   }
 
   &:not(:focus-within) [role='combobox'] {
@@ -49,7 +50,7 @@
 /* The back-button in the doc explorer */
 a.graphiql-doc-explorer-back {
   align-items: center;
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   display: flex;
   text-decoration: none;
 
@@ -58,7 +59,7 @@ a.graphiql-doc-explorer-back {
   }
 
   &:focus {
-    outline: hsla(var(--color-neutral), var(--alpha-secondary)) auto 1px;
+    outline: oklch(var(--fg-muted)) auto 1px;
 
     & + .graphiql-doc-explorer-title {
       /* Don't hide the header when focussing the back link */
@@ -75,28 +76,33 @@ a.graphiql-doc-explorer-back {
 
 /* The title of the currently active page in the doc explorer */
 .graphiql-doc-explorer-title {
-  font-weight: var(--font-weight-medium);
-  font-size: var(--font-size-h2);
+  color: oklch(var(--fg-strong));
+  font-weight: 600;
+  font-size: 12px;
   overflow-x: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+
   &:not(:first-child) {
-    font-size: var(--font-size-h3);
-    margin-top: var(--px-8);
+    margin-top: var(--px-4);
   }
 }
 
 /* The contents of the currently active page in the doc explorer */
+.graphiql-doc-explorer-content {
+  padding: 0 var(--px-14) var(--px-14);
+}
+
 .graphiql-doc-explorer-content > * {
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   margin-top: var(--px-20);
 }
 
 /* Error message */
 .graphiql-doc-explorer-error {
-  background-color: hsla(var(--color-error), var(--alpha-background-heavy));
-  border: 1px solid hsl(var(--color-error));
+  background-color: oklch(var(--accent-red) / 0.15);
+  border: 1px solid oklch(var(--accent-red));
   border-radius: var(--border-radius-8);
-  color: hsl(var(--color-error));
+  color: oklch(var(--accent-red));
   padding: var(--px-8) var(--px-12);
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
index df6d249b595..709c37d4799 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
@@ -1,6 +1,12 @@
 import { isType } from 'graphql';
 import type { FC, ReactNode } from 'react';
-import { ChevronLeftIcon, Spinner, useGraphiQL, pick } from '@graphiql/react';
+import {
+  ChevronLeftIcon,
+  PanelHeader,
+  Spinner,
+  useGraphiQL,
+  pick,
+} from '@graphiql/react';
 import { useDocExplorer, useDocExplorerActions } from '../context';
 import { FieldDocumentation } from './field-documentation';
 import { SchemaDocumentation } from './schema-documentation';
@@ -51,30 +57,36 @@ export const DocExplorer: FC = () => {
     prevName = explorerNavStack.at(-2)!.name;
   }
 
+  const headerTitle = (
+    <div className="graphiql-doc-explorer-header-content">
+      {prevName && (
+        <a
+          href="#"
+          className="graphiql-doc-explorer-back"
+          onClick={event => {
+            event.preventDefault();
+            pop();
+          }}
+          aria-label={`Go back to ${prevName}`}
+        >
+          <ChevronLeftIcon />
+          {prevName}
+        </a>
+      )}
+      <div className="graphiql-doc-explorer-title">{navItem.name}</div>
+    </div>
+  );
+
   return (
     <section
       className="graphiql-doc-explorer"
       aria-label="Documentation Explorer"
     >
       <div className="graphiql-doc-explorer-header">
-        <div className="graphiql-doc-explorer-header-content">
-          {prevName && (
-            <a
-              href="#"
-              className="graphiql-doc-explorer-back"
-              onClick={event => {
-                event.preventDefault();
-                pop();
-              }}
-              aria-label={`Go back to ${prevName}`}
-            >
-              <ChevronLeftIcon />
-              {prevName}
-            </a>
-          )}
-          <div className="graphiql-doc-explorer-title">{navItem.name}</div>
-        </div>
-        <Search key={navItem.name} />
+        <PanelHeader
+          title={headerTitle}
+          actions={<Search key={navItem.name} />}
+        />
       </div>
       <div className="graphiql-doc-explorer-content">{content}</div>
     </section>
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/field-link.css b/packages/graphiql-plugin-doc-explorer/src/components/field-link.css
index ff377b0902b..91a92d12714 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/field-link.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/field-link.css
@@ -1,5 +1,5 @@
 a.graphiql-doc-explorer-field-name {
-  color: hsl(var(--color-info));
+  color: oklch(var(--accent-green-light));
   text-decoration: none;
 
   &:hover {
@@ -7,6 +7,6 @@ a.graphiql-doc-explorer-field-name {
   }
 
   &:focus {
-    outline: hsl(var(--color-info)) auto 1px;
+    outline: oklch(var(--accent-green-light)) auto 1px;
   }
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
index c4e690b4be0..d22d70ebcd5 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
@@ -1,3 +1,3 @@
 .graphiql-doc-explorer-root-type {
-  color: hsl(var(--color-info));
+  color: oklch(var(--fg-muted));
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search.css b/packages/graphiql-plugin-doc-explorer/src/components/search.css
index 8d1a4d02b1e..7d181150974 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/search.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/search.css
@@ -1,21 +1,20 @@
 .graphiql-doc-explorer-search {
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
 
   &:not([data-state='idle']) {
-    border: var(--popover-border);
-    border-radius: var(--border-radius-4);
-    box-shadow: var(--popover-box-shadow);
-    color: hsl(var(--color-neutral));
+    color: oklch(var(--fg-default));
 
     & .graphiql-doc-explorer-search-input {
-      background: hsl(var(--color-base));
+      background: oklch(var(--bg-canvas));
+      border: 1px solid oklch(var(--border-default));
+      box-shadow: 0 4px 12px oklch(0% 0 0 / 0.3);
     }
   }
 }
 
 .graphiql-doc-explorer-search-input {
   align-items: center;
-  background-color: hsla(var(--color-neutral), var(--alpha-background-light));
+  background-color: oklch(var(--fg-default) / 0.08);
   border-radius: var(--border-radius-4);
   display: flex;
   padding: var(--px-8) var(--px-12);
@@ -33,27 +32,30 @@
 }
 
 .graphiql-doc-explorer-search [role='listbox'] {
-  background-color: hsl(var(--color-base));
-  border: none;
-  border-bottom-left-radius: var(--border-radius-4);
-  border-bottom-right-radius: var(--border-radius-4);
-  border-top: 1px solid
-    hsla(var(--color-neutral), var(--alpha-background-heavy));
+  background-color: oklch(var(--bg-canvas));
+  border: 1px solid oklch(var(--border-default));
+  border-radius: var(--border-radius-4);
+  box-shadow: 0 4px 12px oklch(0% 0 0 / 0.3);
   max-height: 400px;
   overflow-y: auto;
   margin: 0;
   font-size: var(--font-size-body);
   padding: var(--px-4);
   /**
-   * This makes sure that the logic for auto-scrolling the search results when
-   * using keyboard navigation works properly (we use `offsetTop` there).
+   * Float below the input as a separate popup so the dropdown does not
+   * appear glued to the panel header. `offsetTop` from the listbox is used
+   * for keyboard auto-scroll, which still works under absolute positioning.
    */
-  position: relative;
+  position: absolute;
+  top: calc(100% + var(--px-4));
+  left: 0;
+  right: 0;
+  z-index: 5;
 }
 
 .graphiql-doc-explorer-search [role='option'] {
   border-radius: var(--border-radius-4);
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   overflow-x: hidden;
   padding: var(--px-8) var(--px-12);
   text-overflow: ellipsis;
@@ -61,18 +63,15 @@
   cursor: pointer;
 
   &[data-headlessui-state='active'] {
-    background-color: hsla(var(--color-neutral), var(--alpha-background-light));
+    background-color: oklch(var(--fg-default) / 0.08);
   }
 
   &:hover {
-    background-color: hsla(
-      var(--color-neutral),
-      var(--alpha-background-medium)
-    );
+    background-color: oklch(var(--fg-default) / 0.12);
   }
 
   &[data-headlessui-state='active']:hover {
-    background-color: hsla(var(--color-neutral), var(--alpha-background-heavy));
+    background-color: oklch(var(--fg-default) / 0.16);
   }
 
   & + & {
@@ -81,19 +80,19 @@
 }
 
 .graphiql-doc-explorer-search-type {
-  color: hsl(var(--color-info));
+  color: oklch(var(--accent-orange));
 }
 
 .graphiql-doc-explorer-search-field {
-  color: hsl(var(--color-warning));
+  color: oklch(var(--accent-green-light));
 }
 
 .graphiql-doc-explorer-search-argument {
-  color: hsl(var(--color-secondary));
+  color: oklch(var(--accent-purple));
 }
 
 .graphiql-doc-explorer-search-divider {
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   font-size: var(--font-size-hint);
   font-weight: var(--font-weight-medium);
   margin-top: var(--px-8);
@@ -101,6 +100,6 @@
 }
 
 .graphiql-doc-explorer-search-empty {
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-muted));
   padding: var(--px-8) var(--px-12);
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.css b/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.css
index 7f65c236ba5..47b9f91a645 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.css
@@ -7,5 +7,5 @@
 }
 
 .graphiql-doc-explorer-enum-value {
-  color: hsl(var(--color-info));
+  color: oklch(var(--accent-green-light));
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-link.css b/packages/graphiql-plugin-doc-explorer/src/components/type-link.css
index afd2048462d..d3278fb62d5 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/type-link.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/type-link.css
@@ -1,5 +1,5 @@
 a.graphiql-doc-explorer-type-name {
-  color: hsl(var(--color-warning));
+  color: oklch(var(--accent-orange));
   text-decoration: none;
 
   &:hover {
@@ -7,6 +7,6 @@ a.graphiql-doc-explorer-type-name {
   }
 
   &:focus {
-    outline: hsl(var(--color-warning)) auto 1px;
+    outline: oklch(var(--accent-orange)) auto 1px;
   }
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx b/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx
new file mode 100644
index 00000000000..d699a79a48b
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx
@@ -0,0 +1,245 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  GraphQLBoolean,
+  GraphQLEnumType,
+  GraphQLInputObjectType,
+  GraphQLInterfaceType,
+  GraphQLList,
+  GraphQLNonNull,
+  GraphQLObjectType,
+  GraphQLSchema,
+  GraphQLString,
+} from 'graphql';
+import { Tooltip } from '@graphiql/react';
+import { DocExplorerStore } from '../context';
+import { TypeDocumentation } from '../components/type-documentation';
+import { FieldDocumentation } from '../components/field-documentation';
+import { SchemaDocumentation } from '../components/schema-documentation';
+import { TypeLink } from '../components/type-link';
+import { FieldLink } from '../components/field-link';
+import { Argument } from '../components/argument';
+
+const EpisodeEnum = new GraphQLEnumType({
+  name: 'Episode',
+  description: 'One of the films in the Star Wars Trilogy',
+  values: {
+    NEWHOPE: { value: 4, description: 'Released in 1977' },
+    EMPIRE: { value: 5, description: 'Released in 1980' },
+    JEDI: {
+      value: 6,
+      description: 'Released in 1983',
+      deprecationReason: 'Use RETURN_OF_THE_JEDI',
+    },
+  },
+});
+
+const CharacterInterface = new GraphQLInterfaceType({
+  name: 'Character',
+  description: 'A character in the Star Wars universe',
+  fields: () => ({
+    id: {
+      type: new GraphQLNonNull(GraphQLString),
+      description: 'Unique identifier',
+    },
+    name: { type: GraphQLString, description: "The character's name" },
+    appearsIn: {
+      type: new GraphQLList(EpisodeEnum),
+      description: 'Which films they appear in',
+    },
+  }),
+});
+
+const ReviewInputType = new GraphQLInputObjectType({
+  name: 'ReviewInput',
+  description: 'Input for creating a film review',
+  fields: {
+    stars: {
+      type: new GraphQLNonNull(GraphQLString),
+      description: 'Number of stars (1–5)',
+    },
+    commentary: {
+      type: GraphQLString,
+      description: 'An optional explanation for the rating',
+    },
+  },
+});
+
+const HumanType = new GraphQLObjectType({
+  name: 'Human',
+  description: 'A humanoid creature in the Star Wars universe',
+  interfaces: [CharacterInterface],
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLString), description: 'Unique ID' },
+    name: { type: GraphQLString, description: 'Name of the human' },
+    homePlanet: {
+      type: GraphQLString,
+      description: 'The home planet of the human, or null if unknown',
+    },
+    appearsIn: {
+      type: new GraphQLList(EpisodeEnum),
+      description: 'Which films they appear in',
+    },
+    friends: {
+      type: new GraphQLList(CharacterInterface),
+      description: 'The friends of the human',
+      deprecationReason: 'Use friendsConnection instead',
+    },
+  }),
+});
+
+const QueryType = new GraphQLObjectType({
+  name: 'Query',
+  description: 'The root query type for the Star Wars API',
+  fields: {
+    hero: {
+      type: CharacterInterface,
+      description: 'Returns the hero of the Star Wars universe',
+      args: {
+        episode: {
+          type: EpisodeEnum,
+          description:
+            'If provided, returns the hero of that particular episode',
+        },
+      },
+    },
+    human: {
+      type: HumanType,
+      description: 'Returns a human character by ID',
+      args: {
+        id: {
+          type: new GraphQLNonNull(GraphQLString),
+          description: 'ID of the human to fetch',
+        },
+      },
+    },
+    isAlive: {
+      type: GraphQLBoolean,
+      deprecationReason: 'Use `hero` with status field instead',
+    },
+  },
+});
+
+const MutationType = new GraphQLObjectType({
+  name: 'Mutation',
+  fields: {
+    createReview: {
+      type: GraphQLBoolean,
+      description: 'Submit a review for a film',
+      args: {
+        episode: { type: EpisodeEnum },
+        review: { type: new GraphQLNonNull(ReviewInputType) },
+      },
+    },
+  },
+});
+
+const StarWarsSchema = new GraphQLSchema({
+  description: 'The Star Wars GraphQL API',
+  query: QueryType,
+  mutation: MutationType,
+  types: [HumanType, CharacterInterface, EpisodeEnum, ReviewInputType],
+});
+
+function withDocExplorerStore(Story: React.FC) {
+  return (
+    <Tooltip.Provider>
+      <DocExplorerStore>
+        <Story />
+      </DocExplorerStore>
+    </Tooltip.Provider>
+  );
+}
+
+const meta: Meta = {
+  title: 'DocExplorer',
+  tags: ['autodocs'],
+  decorators: [withDocExplorerStore],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+export const SchemaOverview: Story = {
+  name: 'Schema overview',
+  render: function SchemaOverviewStory() {
+    return <SchemaDocumentation schema={StarWarsSchema} />;
+  },
+};
+
+export const TypeDetail: Story = {
+  name: 'Type detail (Human)',
+  render: function TypeDetailStory() {
+    return <TypeDocumentation type={HumanType} />;
+  },
+};
+
+export const EnumTypeDetail: Story = {
+  name: 'Type detail (Enum)',
+  render: function EnumTypeDetailStory() {
+    return <TypeDocumentation type={EpisodeEnum} />;
+  },
+};
+
+export const InputTypeDetail: Story = {
+  name: 'Type detail (Input)',
+  render: function InputTypeDetailStory() {
+    return <TypeDocumentation type={ReviewInputType} />;
+  },
+};
+
+export const FieldDetail: Story = {
+  name: 'Field detail',
+  render: function FieldDetailStory() {
+    const heroField = QueryType.getFields()['hero']!;
+    return <FieldDocumentation field={heroField} />;
+  },
+};
+
+export const TokenColors: Story = {
+  name: 'Token colors',
+  render: function TokenColorsStory() {
+    const heroField = QueryType.getFields()['hero']!;
+    const episodeArg = heroField.args[0]!;
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+        <div>
+          <div
+            style={{
+              fontSize: 11,
+              color: 'oklch(var(--fg-muted))',
+              marginBottom: 4,
+            }}
+          >
+            Type link
+          </div>
+          <TypeLink type={HumanType} />
+        </div>
+        <div>
+          <div
+            style={{
+              fontSize: 11,
+              color: 'oklch(var(--fg-muted))',
+              marginBottom: 4,
+            }}
+          >
+            Field link
+          </div>
+          <FieldLink field={heroField} />
+        </div>
+        <div>
+          <div
+            style={{
+              fontSize: 11,
+              color: 'oklch(var(--fg-muted))',
+              marginBottom: 4,
+            }}
+          >
+            Argument
+          </div>
+          <Argument arg={episodeArg} inline />
+        </div>
+      </div>
+    );
+  },
+};
diff --git a/yarn.lock b/yarn.lock
index b903403a4b3..455b489f60d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3252,6 +3252,9 @@ __metadata:
   dependencies:
     "@graphiql/react": "npm:^0.37.4"
     "@headlessui/react": "npm:^2.2"
+    "@storybook/addon-a11y": "npm:^10.3.6"
+    "@storybook/addon-vitest": "npm:^10.3.6"
+    "@storybook/react-vite": "npm:^10.3.6"
     "@testing-library/dom": "npm:^10.4.0"
     "@testing-library/jest-dom": "npm:^6.6.3"
     "@testing-library/react": "npm:^16.3.0"
@@ -3261,6 +3264,7 @@ __metadata:
     react: "npm:^19.1.0"
     react-compiler-runtime: "npm:19.1.0-rc.1"
     react-dom: "npm:^19.1.0"
+    storybook: "npm:^10.3.6"
     vite: "npm:^6.3.4"
     vite-plugin-dts: "npm:^4.5.3"
     zustand: "npm:^5"

From 76a516903250e43096269971fc5ef708bcacce00 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sun, 17 May 2026 17:15:49 -0700
Subject: [PATCH 27/38] v6: Replace Monaco editor themes with v6 token palette
 (#4297)

## Summary

- Rewrite `MONACO_THEME_DATA` in `constants.ts`: both `graphiql-DARK`
and `graphiql-LIGHT` now cover all GraphQL token types (keywords, types,
fields, `$variables`, `@directives`, strings, numbers, operators,
comments) using the v6 accent palette.
- Editor surface colors (suggest widget, hover widget, quick input) move
from the old pink `--color-primary` to `--accent-green`.
- `editor.css`: swaps `hsl(var(--color-primary))` for
`oklch(var(--accent-green))` in the `.highlight` and
`input:focus-visible` rules.
- Adds `monaco-themes.test.ts` to pin token rule shapes for both themes.

## Test plan

- [x] Open the editor, write a query with keywords, type names,
variables, directives, strings, and a comment; confirm syntax colors
match the v6 palette (see the changeset for the token reference).
- [x] Toggle the theme via the settings dropdown; confirm Monaco
switches from dark to light and back, with distinct and correct syntax
colors in each.
- [x] Verify the autocomplete suggestion widget, hover widget, and
quick-input palette use the green accent instead of pink.
- [x] Open the editor with the system set to light mode and no pinned
theme; confirm Monaco uses the light palette.

Refs: graphql/graphiql#4219
---
 .changeset/monaco-theme-v6.md                 |   5 +
 packages/graphiql-react/src/constants.ts      | 160 +++++++++++-------
 .../src/stores/monaco-themes.test.ts          |  90 ++++++++++
 packages/graphiql-react/src/style/editor.css  |   4 +-
 resources/custom-words.txt                    |   1 +
 5 files changed, 198 insertions(+), 62 deletions(-)
 create mode 100644 .changeset/monaco-theme-v6.md
 create mode 100644 packages/graphiql-react/src/stores/monaco-themes.test.ts

diff --git a/.changeset/monaco-theme-v6.md b/.changeset/monaco-theme-v6.md
new file mode 100644
index 00000000000..81c727ecd85
--- /dev/null
+++ b/.changeset/monaco-theme-v6.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Replace the Monaco editor theme with v6-aligned token colors. Both `graphiql-DARK` and `graphiql-LIGHT` now cover all GraphQL token types (keywords, type names, field identifiers, variables, annotations, strings, numbers, comments) using the v6 design's accent palette. UI chrome colors (suggest widget, hover widget, quick input) are updated to match.
diff --git a/packages/graphiql-react/src/constants.ts b/packages/graphiql-react/src/constants.ts
index dfe03495f89..d417eea678b 100644
--- a/packages/graphiql-react/src/constants.ts
+++ b/packages/graphiql-react/src/constants.ts
@@ -174,60 +174,110 @@ export const MONACO_THEME_NAME = {
   light: 'graphiql-LIGHT',
 } as const;
 
-const colors = {
-  transparent: '#ffffff00',
-  bg: {
-    dark: '#212a3b',
-    light: '#ffffffff',
-  },
-  primary: {
-    dark: '#ff5794',
-    light: '#d60590',
-  },
-  primaryBg: {
-    dark: '#ff579419',
-    light: '#d6059019',
+// v6 design token hex values, keyed for Monaco theme rules (no # prefix).
+const TOKEN_COLORS = {
+  dark: {
+    // Foreground
+    fgDefault: 'C9D1D9', // --fg-default
+    fgMuted: '8B949E', // --fg-muted
+    fgDisabled: '6E7681', // --fg-disabled
+    // Accents
+    accentBlue: '79C0FF', // --accent-blue
+    accentGreenLight: '7EE787', // --accent-green-light
+    accentOrange: 'FFA657', // --accent-orange
+    accentPurple: 'D2A8FF', // --accent-purple
+    accentPink: 'FF7B72', // --accent-pink
+    // UI
+    bgCanvas: '0D1117', // --bg-canvas
+    bgOverlay: '21262D', // --bg-overlay
+    accentGreen: '3FB950', // --accent-green (focus/primary)
+    accentGreenBg: '3FB95019',
   },
-  secondary: {
-    dark: '#b7c2d711',
-    light: '#3b4b6811',
+  light: {
+    // Foreground
+    fgDefault: '1F2328', // --fg-default
+    fgMuted: '636E7B', // --fg-muted (~40% oklch)
+    fgDisabled: '9AA3AD', // --fg-disabled (~65% oklch)
+    // Accents — tuned for AA contrast on white
+    accentBlue: '0969DA', // --accent-blue light
+    accentGreenLight: '1A7F37', // --accent-green-light light
+    accentOrange: 'BC4C00', // --accent-orange light
+    accentPurple: '8250DF', // --accent-purple light
+    accentPink: 'CF222E', // --accent-pink light
+    // UI
+    bgCanvas: 'FFFFFF', // --bg-canvas
+    bgOverlay: 'EAEEF2', // --bg-overlay
+    accentGreen: '1A7F37', // --accent-green (focus/primary)
+    accentGreenBg: '1A7F3719',
   },
-};
+} as const;
 
 const getBaseColors = (
   theme: 'dark' | 'light',
-): monaco.editor.IStandaloneThemeData['colors'] => ({
-  'editor.background': colors.transparent, // white with a 00 alpha value
-  'scrollbar.shadow': colors.transparent, // Scrollbar shadow to indicate that the view is scrolled
-  'textLink.foreground': colors.primary[theme], // Foreground color for links in text
-  'textLink.activeForeground': colors.primary[theme], // Foreground color for active links in text
-  'editorLink.activeForeground': colors.primary[theme], // Color of active links
-  'editorHoverWidget.background': colors.bg[theme], // Background color of the editor hover
-  'list.hoverBackground': colors.primaryBg[theme], // List/Tree background when hovering over items using the mouse
-  'list.highlightForeground': colors.primary[theme],
-  'list.focusHighlightForeground': colors.primary[theme],
-  'menu.background': colors.bg[theme], // Background color of the context menu
-
-  'editorSuggestWidget.background': colors.bg[theme], // Background color of the suggest widget
-  'editorSuggestWidget.selectedBackground': colors.primaryBg[theme], // Background color of the selected entry in the suggest widget
-  'editorSuggestWidget.selectedForeground': colors.primary[theme], // Foreground color of the selected entry in the suggest widget
-  'quickInput.background': colors.bg[theme],
-  'quickInputList.focusForeground': theme === 'dark' ? '#ffffff' : '#444444',
-  'highlighted.label': colors.primary[theme],
-  'quickInput.widget': colors.primary[theme],
-  highlight: colors.primary[theme],
-  'editorWidget.background': colors.bg[theme], // Background color of editor widgets, such as find/replace
-  'input.background': colors.secondary[theme], // Input box background
-  focusBorder: colors.primary[theme], // Overall border color for focused elements. This color is only used if not overridden by a component
-  'toolbar.hoverBackground': colors.primaryBg[theme],
-  'inputOption.hoverBackground': colors.primaryBg[theme],
-  'quickInputList.focusBackground': colors.primaryBg[theme],
-  'editorWidget.resizeBorder': colors.primary[theme],
-  'pickerGroup.foreground': colors.primary[theme], // Quick picker color for grouping labels
+): monaco.editor.IStandaloneThemeData['colors'] => {
+  const t = TOKEN_COLORS[theme];
+  return {
+    'editor.background': '#ffffff00', // transparent — editor inherits container bg
+    'scrollbar.shadow': '#ffffff00',
+    'textLink.foreground': `#${t.accentGreen}`,
+    'textLink.activeForeground': `#${t.accentGreen}`,
+    'editorLink.activeForeground': `#${t.accentGreen}`,
+    'editorHoverWidget.background': `#${t.bgCanvas}`,
+    'list.hoverBackground': `#${t.accentGreenBg}`,
+    'list.highlightForeground': `#${t.accentGreen}`,
+    'list.focusHighlightForeground': `#${t.accentGreen}`,
+    'menu.background': `#${t.bgCanvas}`,
+    'editorSuggestWidget.background': `#${t.bgCanvas}`,
+    'editorSuggestWidget.selectedBackground': `#${t.accentGreenBg}`,
+    'editorSuggestWidget.selectedForeground': `#${t.accentGreen}`,
+    'quickInput.background': `#${t.bgCanvas}`,
+    'quickInputList.focusForeground': theme === 'dark' ? '#ffffff' : '#444444',
+    'editorWidget.background': `#${t.bgCanvas}`,
+    'input.background': `#${t.bgOverlay}`,
+    focusBorder: `#${t.accentGreen}`,
+    'toolbar.hoverBackground': `#${t.accentGreenBg}`,
+    'inputOption.hoverBackground': `#${t.accentGreenBg}`,
+    'quickInputList.focusBackground': `#${t.accentGreenBg}`,
+    'editorWidget.resizeBorder': `#${t.accentGreen}`,
+    'pickerGroup.foreground': `#${t.accentGreen}`,
+    'menu.selectionBackground': `#${t.accentGreenBg}`,
+    'menu.selectionForeground': `#${t.accentGreen}`,
+  };
+};
 
-  'menu.selectionBackground': colors.primaryBg[theme], // hover background
-  'menu.selectionForeground': colors.primary[theme], // hover text color
-});
+const getTokenRules = (
+  theme: 'dark' | 'light',
+): monaco.editor.ITokenThemeRule[] => {
+  const t = TOKEN_COLORS[theme];
+  return [
+    // keywords: query, mutation, subscription, fragment, on, type, scalar, …
+    { token: 'keyword.gql', foreground: t.accentPink },
+    // field / argument names (lowercase identifiers)
+    { token: 'key.identifier.gql', foreground: t.fgDefault },
+    // $variable input variables
+    { token: 'argument.identifier.gql', foreground: t.accentBlue },
+    // TypeName (uppercase identifiers)
+    { token: 'type.identifier.gql', foreground: t.accentOrange },
+    // @directives
+    { token: 'annotation.gql', foreground: t.accentPurple },
+    // string literals
+    { token: 'string.gql', foreground: t.accentBlue },
+    { token: 'string.quote.gql', foreground: t.accentBlue },
+    { token: 'string.escape.gql', foreground: t.accentBlue },
+    // numbers
+    { token: 'number.gql', foreground: t.accentBlue },
+    { token: 'number.float.gql', foreground: t.accentBlue },
+    // operators and delimiters use muted foreground
+    { token: 'operator.gql', foreground: t.fgMuted },
+    { token: 'delimiter.gql', foreground: t.fgMuted },
+    // comments
+    { token: 'comment.gql', foreground: t.fgDisabled, fontStyle: 'italic' },
+    // definition names (identifiers following 'fragment'/'query'/etc.)
+    // are caught by key.identifier.gql above, but named fragments benefit
+    // from the green-light accent to mirror the design's "name" slot.
+    { token: 'identifier.gql', foreground: t.accentGreenLight },
+  ];
+};
 
 export const MONACO_THEME_DATA: Record<
   'dark' | 'light',
@@ -237,22 +287,12 @@ export const MONACO_THEME_DATA: Record<
     base: 'vs-dark',
     inherit: true,
     colors: getBaseColors('dark'),
-    rules: [
-      {
-        token: 'argument.identifier.gql',
-        foreground: '#908aff',
-      },
-    ],
+    rules: getTokenRules('dark'),
   },
   light: {
     base: 'vs',
     inherit: true,
     colors: getBaseColors('light'),
-    rules: [
-      {
-        token: 'argument.identifier.gql',
-        foreground: '#6c69ce',
-      },
-    ],
+    rules: getTokenRules('light'),
   },
 };
diff --git a/packages/graphiql-react/src/stores/monaco-themes.test.ts b/packages/graphiql-react/src/stores/monaco-themes.test.ts
new file mode 100644
index 00000000000..0a9ab374833
--- /dev/null
+++ b/packages/graphiql-react/src/stores/monaco-themes.test.ts
@@ -0,0 +1,90 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { MONACO_THEME_DATA, MONACO_THEME_NAME } from '../constants';
+
+describe('MONACO_THEME_NAME', () => {
+  it('exports stable theme name constants', () => {
+    expect(MONACO_THEME_NAME.dark).toBe('graphiql-DARK');
+    expect(MONACO_THEME_NAME.light).toBe('graphiql-LIGHT');
+  });
+});
+
+describe('MONACO_THEME_DATA dark', () => {
+  const { dark } = MONACO_THEME_DATA;
+
+  it('uses vs-dark as base', () => {
+    expect(dark.base).toBe('vs-dark');
+    expect(dark.inherit).toBe(true);
+  });
+
+  it('has a transparent editor background', () => {
+    expect(dark.colors?.['editor.background']).toBe('#ffffff00');
+  });
+
+  it('colors keyword tokens with accent-pink', () => {
+    const rule = dark.rules.find(r => r.token === 'keyword.gql');
+    expect(rule?.foreground).toBe('FF7B72');
+  });
+
+  it('colors type identifiers with accent-orange', () => {
+    const rule = dark.rules.find(r => r.token === 'type.identifier.gql');
+    expect(rule?.foreground).toBe('FFA657');
+  });
+
+  it('colors variable arguments with accent-blue', () => {
+    const rule = dark.rules.find(r => r.token === 'argument.identifier.gql');
+    expect(rule?.foreground).toBe('79C0FF');
+  });
+
+  it('colors annotations with accent-purple', () => {
+    const rule = dark.rules.find(r => r.token === 'annotation.gql');
+    expect(rule?.foreground).toBe('D2A8FF');
+  });
+
+  it('italicizes comments', () => {
+    const rule = dark.rules.find(r => r.token === 'comment.gql');
+    expect(rule?.fontStyle).toBe('italic');
+  });
+});
+
+describe('MONACO_THEME_DATA light', () => {
+  const { light } = MONACO_THEME_DATA;
+
+  it('uses vs as base', () => {
+    expect(light.base).toBe('vs');
+    expect(light.inherit).toBe(true);
+  });
+
+  it('has a transparent editor background', () => {
+    expect(light.colors?.['editor.background']).toBe('#ffffff00');
+  });
+
+  it('colors keyword tokens with accent-pink light variant', () => {
+    const rule = light.rules.find(r => r.token === 'keyword.gql');
+    expect(rule?.foreground).toBe('CF222E');
+  });
+
+  it('colors type identifiers with accent-orange light variant', () => {
+    const rule = light.rules.find(r => r.token === 'type.identifier.gql');
+    expect(rule?.foreground).toBe('BC4C00');
+  });
+
+  it('colors variable arguments with accent-blue light variant', () => {
+    const rule = light.rules.find(r => r.token === 'argument.identifier.gql');
+    expect(rule?.foreground).toBe('0969DA');
+  });
+
+  it('italicizes comments', () => {
+    const rule = light.rules.find(r => r.token === 'comment.gql');
+    expect(rule?.fontStyle).toBe('italic');
+  });
+});
+
+describe('MONACO_THEME_DATA symmetry', () => {
+  it('dark and light themes cover the same token types', () => {
+    const darkTokens = MONACO_THEME_DATA.dark.rules.map(r => r.token).sort();
+    const lightTokens = MONACO_THEME_DATA.light.rules.map(r => r.token).sort();
+    expect(darkTokens).toEqual(lightTokens);
+  });
+});
diff --git a/packages/graphiql-react/src/style/editor.css b/packages/graphiql-react/src/style/editor.css
index d1d1eb0c95d..2d2a9fc591d 100644
--- a/packages/graphiql-react/src/style/editor.css
+++ b/packages/graphiql-react/src/style/editor.css
@@ -17,11 +17,11 @@
   outline-width: 0 !important;
 
   .highlight {
-    color: hsl(var(--color-primary)) !important;
+    color: oklch(var(--accent-green)) !important;
   }
 
   input:focus-visible {
-    outline-color: hsl(var(--color-primary));
+    outline-color: oklch(var(--accent-green));
   }
 
   /* Command pallet F1 styles */
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index eb1cc28a269..90bde5dbf73 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -70,6 +70,7 @@ dotan
 dotansimha
 edcore
 envrc
+EAEEF
 esbuild
 estree
 execa

From ce7a88f7bb58828d1faf78d8ea21eb34306ed157 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Mon, 18 May 2026 08:08:52 -0700
Subject: [PATCH 28/38] Speed up monaco-graphql bundle assertion test (#4298)

## Summary

- Replaces the `examples/monaco-graphql-react-vite` build target with a
minimal fixture under
`packages/monaco-graphql/__fixtures__/bundle-test/` that imports only
`monaco-graphql`'s public API and wires graphql + json workers. No
React, no example-app baggage, no TypeScript language support.
- Replaces the previous `execa`-driven `yarn workspace ... build`
shell-out with Vite's programmatic `build()` API. Drops `write: false`,
`minify: false`, `target: 'esnext'`, `reportCompressedSize: false`, and
`treeshake: false` since the assertion only cares about the chunk file
list, not the bundle contents or size.
- Adds an explicit negative regex assertion against
`/typescript|tsMode|tsWorker|ts\.worker|cssMode|css\.worker|htmlMode|html\.worker/i`,
so the test's intent ("don't bundle unwanted Monaco language modules")
is readable from the assertion, not just the snapshot.
- Removes the now-unused `execa` devDependency.
- Local test runtime drops from ~8.5s to ~2.3s. CI runtime is ~32s,
dominated by Rollup traversing monaco-editor's module graph; the new
minimal-fixture surface and dropped transforms don't change that floor.
Vitest timeout set to 60s (~28s headroom).

## Test plan

- [x] Run `yarn workspace monaco-graphql test` and confirm both tests
pass in under 5s locally.
- [x] Confirm the snapshot lists only editor core, graphql, and json
chunks (no TypeScript, CSS, or HTML language service modules).
- [x] Sanity-check the negative assertion by manually adding a
TypeScript worker import to the fixture, rerunning the test, and
confirming it fails with the explicit message before reverting.
---
 .../__fixtures__/bundle-test/index.html       |  9 ++
 .../__fixtures__/bundle-test/index.ts         | 16 ++++
 .../__tests__/monaco-editor.test.ts           | 92 ++++++++++++-------
 packages/monaco-graphql/package.json          |  1 -
 resources/custom-words.txt                    |  1 +
 yarn.lock                                     |  1 -
 6 files changed, 86 insertions(+), 34 deletions(-)
 create mode 100644 packages/monaco-graphql/__fixtures__/bundle-test/index.html
 create mode 100644 packages/monaco-graphql/__fixtures__/bundle-test/index.ts

diff --git a/packages/monaco-graphql/__fixtures__/bundle-test/index.html b/packages/monaco-graphql/__fixtures__/bundle-test/index.html
new file mode 100644
index 00000000000..b78bb95423a
--- /dev/null
+++ b/packages/monaco-graphql/__fixtures__/bundle-test/index.html
@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="UTF-8" />
+  </head>
+  <body>
+    <script type="module" src="./index.ts"></script>
+  </body>
+</html>
diff --git a/packages/monaco-graphql/__fixtures__/bundle-test/index.ts b/packages/monaco-graphql/__fixtures__/bundle-test/index.ts
new file mode 100644
index 00000000000..b06daa901c3
--- /dev/null
+++ b/packages/monaco-graphql/__fixtures__/bundle-test/index.ts
@@ -0,0 +1,16 @@
+import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker.js?worker';
+import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker.js?worker';
+import GraphQLWorker from 'monaco-graphql/esm/graphql.worker.js?worker';
+import 'monaco-graphql';
+
+globalThis.MonacoEnvironment = {
+  getWorker(_workerId: string, label: string) {
+    switch (label) {
+      case 'json':
+        return new JsonWorker();
+      case 'graphql':
+        return new GraphQLWorker();
+    }
+    return new EditorWorker();
+  },
+};
diff --git a/packages/monaco-graphql/__tests__/monaco-editor.test.ts b/packages/monaco-graphql/__tests__/monaco-editor.test.ts
index 4f0aac0abd5..abde426af94 100644
--- a/packages/monaco-graphql/__tests__/monaco-editor.test.ts
+++ b/packages/monaco-graphql/__tests__/monaco-editor.test.ts
@@ -1,41 +1,69 @@
 import { describe, it, expect } from 'vitest';
-import { $ } from 'execa';
+import { build, type UserConfig } from 'vite';
+import path from 'node:path';
 
-// eslint-disable-next-line no-control-regex
-const ANSI_COLOR_REGEX = /\u001b\[\d+m/g;
-
-const VOLATILE_LINE =
-  /modules transformed|rendering chunks|computing gzip size|transforming|built in|building for production/;
+const FIXTURE_ROOT = path.resolve(
+  import.meta.dirname,
+  '../__fixtures__/bundle-test',
+);
 
 describe('monaco-editor', () => {
-  it('should include in bundle only graphql/json languages', async () => {
-    const { stdout } =
-      await $`yarn workspace example-monaco-graphql-react-vite build`;
-    // When process.env.CI is set, stdout contains ANSI color codes, and vite doesn't have
-    // `--no-colors` flag
-    const files = stdout
-      .replaceAll(ANSI_COLOR_REGEX, '')
-      .split('\n')
-      .map(line => line.replaceAll(/\s{2,}.*/gm, '').trim())
-      .filter(line => line && !VOLATILE_LINE.test(line));
+  it('should not bundle Monaco language modules beyond graphql and json', async () => {
+    const result = await build({
+      root: FIXTURE_ROOT,
+      logLevel: 'warn',
+      build: {
+        write: false,
+        minify: false,
+        target: 'esnext',
+        reportCompressedSize: false,
+        rollupOptions: {
+          treeshake: false,
+          output: {
+            entryFileNames: '[name].js',
+            chunkFileNames: 'assets/[name].js',
+            assetFileNames: 'assets/[name].[ext]',
+          },
+        },
+      },
+      worker: {
+        format: 'es',
+        rollupOptions: {
+          treeshake: false,
+          output: {
+            entryFileNames: 'workers/[name].js',
+            chunkFileNames: 'workers/[name].js',
+          },
+        },
+      },
+    } satisfies UserConfig);
+
+    const mainOutput = Array.isArray(result) ? result[0] : result;
+    const files = mainOutput.output.map(chunk => chunk.fileName).sort();
+
+    // Explicit negative assertion: importing monaco-graphql must not pull in
+    // TypeScript, CSS, or HTML language services. A consumer who only wants
+    // GraphQL + JSON should not be forced to ship them.
+    for (const file of files) {
+      expect(file).not.toMatch(
+        /typescript|tsMode|tsWorker|ts\.worker|cssMode|css\.worker|htmlMode|html\.worker/i,
+      );
+    }
+
     expect(files).toMatchInlineSnapshot(`
       [
-        "dist/index.html",
-        "dist/workers/graphql.js",
-        "dist/assets/codicon.ttf",
-        "dist/workers/standalone.js",
-        "dist/workers/editor.worker.js",
-        "dist/workers/json.worker.js",
-        "dist/workers/graphql.worker.js",
-        "dist/workers/ts.worker.js",
-        "dist/assets/index.css",
-        "dist/assets/graphql.js",
-        "dist/assets/typescript.js",
-        "dist/assets/index.js",
-        "dist/assets/tsMode.js",
-        "dist/assets/jsonMode.js",
-        "dist/assets/graphqlMode.js",
-        "dist/index.js",
+        "assets/codicon.ttf",
+        "assets/graphql.js",
+        "assets/graphqlMode.js",
+        "assets/index.css",
+        "assets/jsonMode.js",
+        "index.html",
+        "index.js",
+        "workers/editor.worker.js",
+        "workers/graphql.js",
+        "workers/graphql.worker.js",
+        "workers/json.worker.js",
+        "workers/standalone.js",
       ]
     `);
   }, 60_000);
diff --git a/packages/monaco-graphql/package.json b/packages/monaco-graphql/package.json
index c165d2cbdd5..cd35db65a16 100644
--- a/packages/monaco-graphql/package.json
+++ b/packages/monaco-graphql/package.json
@@ -76,7 +76,6 @@
     "picomatch-browser": "^2.2.6"
   },
   "devDependencies": {
-    "execa": "^7.1.1",
     "graphql": "^16.9.0",
     "monaco-editor": "0.52.2",
     "prettier": "3.3.2",
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index 90bde5dbf73..01c1e6ffce9 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -229,6 +229,7 @@ therox
 thomasheyenbrock
 timsuchanek
 tokenizes
+treeshake
 tsup
 turbopack
 typeahead
diff --git a/yarn.lock b/yarn.lock
index 455b489f60d..cf164b5cf50 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -17112,7 +17112,6 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "monaco-graphql@workspace:packages/monaco-graphql"
   dependencies:
-    execa: "npm:^7.1.1"
     graphql: "npm:^16.9.0"
     graphql-language-service: "npm:^5.5.1"
     monaco-editor: "npm:0.52.2"

From dabeb6dccba58d4b61c042b6a596f870cf0ce3fb Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Mon, 18 May 2026 19:52:14 -0700
Subject: [PATCH 29/38] v6: Add OS-aware `MODIFIER` constants to `KeycapHint`
 (#4302)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

`KeycapHint` callers now use semantic names (`MODIFIER.Meta`, etc.) and
the component renders the right glyph or text per OS. `MODIFIER.Meta`
becomes `⌘` on macOS and `Ctrl` on other platforms; `Ctrl`/`Alt`/`Shift`
become Mac glyphs (`⌃`/`⌥`/`⇧`) on macOS and plain text elsewhere.
`Enter` always renders as `⏎`.

## Test plan

- [ ] Open Storybook `Primitives/KeycapHint` on macOS: chips render as
⌘/⏎.
- [ ] In Chrome devtools, override the user agent to a Windows or Linux
UA and reload Storybook: same stories render as Ctrl/⏎.
- [ ] Confirm the run-shortcut chip and command-palette chip in the top
bar follow the same OS detection.
---
 .changeset/keycap-hint-os-detection.md        |  5 ++
 .../graphiql-react/src/components/index.ts    |  4 +-
 .../src/components/keycap-hint/index.tsx      | 56 +++++++++++++++----
 .../keycap-hint/keycap-hint.macos.test.tsx    | 38 +++++++++++++
 .../keycap-hint/keycap-hint.stories.tsx       |  8 ++-
 .../keycap-hint/keycap-hint.test.tsx          | 44 ++++++++++++---
 .../src/components/top-bar/index.tsx          | 12 +++-
 7 files changed, 142 insertions(+), 25 deletions(-)
 create mode 100644 .changeset/keycap-hint-os-detection.md
 create mode 100644 packages/graphiql-react/src/components/keycap-hint/keycap-hint.macos.test.tsx

diff --git a/.changeset/keycap-hint-os-detection.md b/.changeset/keycap-hint-os-detection.md
new file mode 100644
index 00000000000..1bb7f7544fe
--- /dev/null
+++ b/.changeset/keycap-hint-os-detection.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+`KeycapHint` now takes semantic modifier names via the new `MODIFIER` constant. `MODIFIER.Meta` renders as `⌘` on macOS and `Ctrl` elsewhere; `Ctrl`/`Alt`/`Shift` render as Mac glyphs (`⌃`/`⌥`/`⇧`) on macOS and as plain text on other platforms. `Enter` renders as `⏎` on every platform.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index 5e9363cc35f..ad40498772f 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -18,8 +18,8 @@ export { Spinner } from './spinner';
 export { Tabs, Tab } from './tabs';
 export { Tooltip } from './tooltip';
 export { Root as VisuallyHidden } from '@radix-ui/react-visually-hidden';
-export { KeycapHint } from './keycap-hint';
-export type { KeycapHintProps } from './keycap-hint';
+export { KeycapHint, MODIFIER } from './keycap-hint';
+export type { KeycapHintProps, ModifierKey } from './keycap-hint';
 export { PanelHeader } from './panel-header';
 export type { PanelHeaderProps } from './panel-header';
 export { SegmentedControl } from './segmented-control';
diff --git a/packages/graphiql-react/src/components/keycap-hint/index.tsx b/packages/graphiql-react/src/components/keycap-hint/index.tsx
index 70c8916751e..341130321f6 100644
--- a/packages/graphiql-react/src/components/keycap-hint/index.tsx
+++ b/packages/graphiql-react/src/components/keycap-hint/index.tsx
@@ -1,17 +1,53 @@
 import type { FC } from 'react';
+import { isMacOs } from '../../constants';
 import './index.css';
 
+/**
+ * Semantic modifier keys for `KeycapHint`.
+ *
+ * - `Meta` is the OS-appropriate shortcut modifier: ⌘ on macOS, Ctrl elsewhere.
+ * - `Ctrl`/`Alt`/`Shift` render as Mac glyphs (⌃/⌥/⇧) on macOS and as plain
+ *   text on other platforms.
+ * - `Enter` always renders as ⏎ (the symbol is widely recognized cross-platform).
+ */
+export const MODIFIER = Object.freeze({
+  Meta: 'Meta',
+  Ctrl: 'Ctrl',
+  Alt: 'Alt',
+  Shift: 'Shift',
+  Enter: 'Enter',
+} as const);
+
+export type ModifierKey = (typeof MODIFIER)[keyof typeof MODIFIER];
+
 export type KeycapHintProps = {
-  keys: string[];
+  /** Keys to render. Use `MODIFIER.*` for OS-aware modifiers; other strings render as-is. */
+  keys: Array<ModifierKey | (string & {})>;
   ariaLabel: string;
 };
 
-export const KeycapHint: FC<KeycapHintProps> = ({ keys, ariaLabel }) => (
-  <span className="graphiql-keycap-hint" aria-label={ariaLabel}>
-    {keys.map((k, i) => (
-      <kbd key={`${k}-${i}`} className="graphiql-keycap">
-        {k}
-      </kbd>
-    ))}
-  </span>
-);
+const MAC_DISPLAY: Record<string, string> = {
+  Meta: '⌘',
+  Ctrl: '⌃',
+  Alt: '⌥',
+  Shift: '⇧',
+  Enter: '⏎',
+};
+
+const NON_MAC_DISPLAY: Record<string, string> = {
+  Meta: 'Ctrl',
+  Enter: '⏎',
+};
+
+export const KeycapHint: FC<KeycapHintProps> = ({ keys, ariaLabel }) => {
+  const display = isMacOs ? MAC_DISPLAY : NON_MAC_DISPLAY;
+  return (
+    <span className="graphiql-keycap-hint" aria-label={ariaLabel}>
+      {keys.map((k, i) => (
+        <kbd key={`${k}-${i}`} className="graphiql-keycap">
+          {display[k] ?? k}
+        </kbd>
+      ))}
+    </span>
+  );
+};
diff --git a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.macos.test.tsx b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.macos.test.tsx
new file mode 100644
index 00000000000..25c26f9406a
--- /dev/null
+++ b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.macos.test.tsx
@@ -0,0 +1,38 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+
+vi.mock('../../constants', async () => {
+  const actual =
+    await vi.importActual<typeof import('../../constants')>('../../constants');
+  return { ...actual, isMacOs: true };
+});
+
+import { KeycapHint, MODIFIER } from './';
+
+describe('KeycapHint (macOS)', () => {
+  it('renders MODIFIER.Meta as "⌘"', () => {
+    render(
+      <KeycapHint
+        keys={[MODIFIER.Meta, 'K']}
+        ariaLabel="Open command palette"
+      />,
+    );
+    expect(screen.getByText('⌘')).toBeInTheDocument();
+    expect(screen.getByText('K')).toBeInTheDocument();
+  });
+
+  it('renders other modifiers as their Mac glyphs', () => {
+    render(
+      <KeycapHint
+        keys={[MODIFIER.Ctrl, MODIFIER.Alt, MODIFIER.Shift, MODIFIER.Enter]}
+        ariaLabel="All modifiers"
+      />,
+    );
+    expect(screen.getByText('⌃')).toBeInTheDocument();
+    expect(screen.getByText('⌥')).toBeInTheDocument();
+    expect(screen.getByText('⇧')).toBeInTheDocument();
+    expect(screen.getByText('⏎')).toBeInTheDocument();
+  });
+});
diff --git a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
index 9e8baa3e93b..4b90351cb48 100644
--- a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
+++ b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.stories.tsx
@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
-import { KeycapHint } from './';
+import { KeycapHint, MODIFIER } from './';
 
 const meta: Meta<typeof KeycapHint> = {
   title: 'Primitives/KeycapHint',
@@ -16,10 +16,12 @@ export const Single: Story = {
 
 export const ChordWithModifier: Story = {
   render: () => (
-    <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />
+    <KeycapHint keys={[MODIFIER.Meta, 'K']} ariaLabel="Open command palette" />
   ),
 };
 
 export const RunShortcut: Story = {
-  render: () => <KeycapHint keys={['⌘', '⏎']} ariaLabel="Run query" />,
+  render: () => (
+    <KeycapHint keys={[MODIFIER.Meta, MODIFIER.Enter]} ariaLabel="Run query" />
+  ),
 };
diff --git a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx
index f502c8c2446..11834e6d378 100644
--- a/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx
+++ b/packages/graphiql-react/src/components/keycap-hint/keycap-hint.test.tsx
@@ -2,25 +2,55 @@
 
 import { describe, it, expect } from 'vitest';
 import { render, screen } from '@testing-library/react';
-import { KeycapHint } from './';
+import { KeycapHint, MODIFIER } from './';
 
-describe('KeycapHint', () => {
-  it('renders the provided keys', () => {
-    render(<KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />);
-    expect(screen.getByText('⌘')).toBeInTheDocument();
+// jsdom's default userAgent does not include "Mac", so `isMacOs` is false here.
+describe('KeycapHint (non-macOS)', () => {
+  it('renders MODIFIER.Meta as "Ctrl"', () => {
+    render(
+      <KeycapHint
+        keys={[MODIFIER.Meta, 'K']}
+        ariaLabel="Open command palette"
+      />,
+    );
+    expect(screen.getByText('Ctrl')).toBeInTheDocument();
     expect(screen.getByText('K')).toBeInTheDocument();
   });
 
+  it('renders other modifiers as plain text', () => {
+    render(
+      <KeycapHint keys={[MODIFIER.Shift, MODIFIER.Alt]} ariaLabel="Combo" />,
+    );
+    expect(screen.getByText('Shift')).toBeInTheDocument();
+    expect(screen.getByText('Alt')).toBeInTheDocument();
+  });
+
+  it('always renders Enter as ⏎', () => {
+    render(<KeycapHint keys={[MODIFIER.Enter]} ariaLabel="Submit" />);
+    expect(screen.getByText('⏎')).toBeInTheDocument();
+  });
+
+  it('passes unknown strings through unchanged', () => {
+    render(<KeycapHint keys={['F1']} ariaLabel="Command palette" />);
+    expect(screen.getByText('F1')).toBeInTheDocument();
+  });
+
   it('exposes the shortcut as an accessible name', () => {
     render(
-      <KeycapHint keys={['⌘', 'Enter']} ariaLabel="Run query (Cmd+Enter)" />,
+      <KeycapHint
+        keys={[MODIFIER.Meta, MODIFIER.Enter]}
+        ariaLabel="Run query (Ctrl+Enter)"
+      />,
     );
     expect(screen.getByLabelText(/Run query/i)).toBeInTheDocument();
   });
 
   it('renders a <kbd> element for each key', () => {
     const { container } = render(
-      <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />,
+      <KeycapHint
+        keys={[MODIFIER.Meta, 'K']}
+        ariaLabel="Open command palette"
+      />,
     );
     expect(container.querySelectorAll('kbd')).toHaveLength(2);
   });
diff --git a/packages/graphiql-react/src/components/top-bar/index.tsx b/packages/graphiql-react/src/components/top-bar/index.tsx
index 20f7c9ab619..b3b54a85cf6 100644
--- a/packages/graphiql-react/src/components/top-bar/index.tsx
+++ b/packages/graphiql-react/src/components/top-bar/index.tsx
@@ -4,7 +4,7 @@
 
 import type { FC } from 'react';
 import { useGraphiQL, useGraphiQLActions } from '../provider';
-import { KeycapHint } from '../keycap-hint';
+import { KeycapHint, MODIFIER } from '../keycap-hint';
 import './index.css';
 
 export type TopBarProps = {
@@ -60,7 +60,10 @@ export const TopBarView: FC<TopBarViewProps> = ({
 
       <button type="button" className="graphiql-top-bar-cmd">
         <span>Jump to schema</span>
-        <KeycapHint keys={['⌘', 'K']} ariaLabel="Open command palette" />
+        <KeycapHint
+          keys={[MODIFIER.Meta, 'K']}
+          ariaLabel="Open command palette"
+        />
       </button>
 
       <button
@@ -71,7 +74,10 @@ export const TopBarView: FC<TopBarViewProps> = ({
         aria-label="Run query"
       >
         Run
-        <KeycapHint keys={['⌘', '⏎']} ariaLabel="Run query shortcut" />
+        <KeycapHint
+          keys={[MODIFIER.Meta, MODIFIER.Enter]}
+          ariaLabel="Run query shortcut"
+        />
       </button>
     </header>
   );

From b73d9513dffcbb9ad2c3ceebff79208be85c8f6d Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Wed, 20 May 2026 13:56:30 -0700
Subject: [PATCH 30/38] v6: Redesign Schema Explorer panel structure (#4299)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- `PanelHeader` for the docs panel becomes a fixed eyebrow label,
`Schema Explorer`. The type name moves into a new breadcrumb row below
the header.
- New `SchemaDocumentation` root view: two eyebrow sections (`ROOT
TYPES` and `ALL SCHEMA TYPES · N`) replace the old accordion. Root
operation rows show a `MethodPill` and target type name. All-types rows
show a kind badge (`TYPE`, `SCALAR`, `ENUM`, `INPUT`, `INTERFACE`,
`UNION`) and type name in mono.
- New `Breadcrumb` row: mono font, depth segments color-coded as
`--accent-blue` / `--accent-green-light` / `--fg-strong`, chevron
separators; clicking a segment navigates back to that depth.
- New `SearchRow` content-area component: inline `Search schema` input
with keycap hint; listbox renders as a floating popover in the content
area, replacing the old absolutely-positioned search overlay.
- New `TypeCard`: `TYPE` badge (mono, uppercase, accent-blue tinted),
type name in mono, description, and an `implements X · Y` row with
`--accent-orange` links.
- New `FieldsList`: collapsible `FIELDS · N` header, mono rows with
field name in `--accent-green-light`, colon in `--fg-muted`, return type
in `--accent-orange`, optional description in `--fg-subtle`, and a 2px
`--accent-blue` left border on the active row. Horizontal padding bumped
to 16px across all content sections for breathing room.
- `TypeDocumentation` gains a `hideHeader` prop so it can suppress its
own description / implements / fields block when `TypeCard` +
`FieldsList` render those above.

## Test plan

- [ ] Open the Docs panel. Confirm the header shows `SCHEMA EXPLORER`
with no extra buttons, a search input, and two eyebrow sections: `ROOT
TYPES` and `ALL SCHEMA TYPES · N`.
- [ ] Confirm each root operation row shows its `MethodPill`
(`QRY`/`MUT`/`SUB`), operation label, and target type name. Click a row
and confirm it navigates into the type detail.
- [ ] In `ALL SCHEMA TYPES`, confirm each row shows a kind badge and
mono type name. Click a row and confirm navigation.
- [ ] Confirm the breadcrumb row appears below the header when inside a
type, with color-coded segments. Click an intermediate segment and
confirm it navigates back.
- [ ] Confirm `TypeCard` shows the kind badge, name, description, and
`implements` list for an object type that implements interfaces.
- [ ] Confirm `FieldsList` shows mono rows with green field names and
orange return types; click a field row and confirm it navigates in.
- [ ] Type in the inline search row and confirm the listbox popover
appears with results.
- [ ] Toggle light / dark theme; confirm root view and type-detail both
render correctly.
- [ ] Navigate to an enum type and confirm enum values still render
below.

Refs: graphql/graphiql#4219
---
 .changeset/doc-explorer-redesign.md           |   5 +
 .../__tests__/doc-explorer.spec.tsx           |  87 +++++---
 .../__tests__/field-documentation.spec.tsx    |  10 +-
 .../src/components/arguments-list.css         | 140 +++++++++++++
 .../src/components/arguments-list.tsx         | 115 +++++++++++
 .../src/components/breadcrumb.css             |  50 +++++
 .../src/components/breadcrumb.tsx             |  62 ++++++
 .../src/components/doc-explorer.css           | 127 ++++--------
 .../src/components/doc-explorer.tsx           |  93 +++++----
 .../src/components/field-card.css             |  45 ++++
 .../src/components/field-card.tsx             |  44 ++++
 .../src/components/field-documentation.tsx    |  80 +++-----
 .../src/components/fields-list.css            | 130 ++++++++++++
 .../src/components/fields-list.tsx            | 137 +++++++++++++
 .../src/components/index.ts                   |   6 +
 .../src/components/schema-documentation.css   |  88 +++++++-
 .../src/components/schema-documentation.tsx   | 174 +++++++++++-----
 .../src/components/search-row.css             |  87 ++++++++
 .../src/components/search-row.tsx             | 192 ++++++++++++++++++
 .../src/components/search.css                 |  12 +-
 .../src/components/search.tsx                 |   8 +-
 .../src/components/type-card.css              |  76 +++++++
 .../src/components/type-card.tsx              |  92 +++++++++
 .../src/components/type-documentation.tsx     |  17 +-
 .../src/context.tsx                           |   2 +-
 .../src/stories/doc-explorer.stories.tsx      |  85 ++++++--
 packages/graphiql/cypress/e2e/docs.cy.ts      |  59 +++---
 27 files changed, 1707 insertions(+), 316 deletions(-)
 create mode 100644 .changeset/doc-explorer-redesign.md
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/arguments-list.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/field-card.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/field-card.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/fields-list.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/fields-list.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/search-row.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/type-card.css
 create mode 100644 packages/graphiql-plugin-doc-explorer/src/components/type-card.tsx

diff --git a/.changeset/doc-explorer-redesign.md b/.changeset/doc-explorer-redesign.md
new file mode 100644
index 00000000000..52a34b662ef
--- /dev/null
+++ b/.changeset/doc-explorer-redesign.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/plugin-doc-explorer': minor
+---
+
+Redesign the Schema Explorer panel: eyebrow header with filter and search icon buttons, dedicated breadcrumb row with color-coded depth segments, inline search row with keycap hint, type card with TYPE badge and implements list, and a mono field list with type colors and active-row accent border.
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/__tests__/doc-explorer.spec.tsx b/packages/graphiql-plugin-doc-explorer/src/components/__tests__/doc-explorer.spec.tsx
index fe10367daba..324385ccf55 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/__tests__/doc-explorer.spec.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/__tests__/doc-explorer.spec.tsx
@@ -1,5 +1,5 @@
 import { type Mock, describe, it, expect, vi, beforeEach } from 'vitest';
-import { useGraphiQL as $useGraphiQL } from '@graphiql/react';
+import { useGraphiQL as $useGraphiQL, Tooltip } from '@graphiql/react';
 import { render } from '@testing-library/react';
 import { GraphQLInt, GraphQLObjectType, GraphQLSchema } from 'graphql';
 import { FC, useEffect } from 'react';
@@ -54,9 +54,11 @@ const withErrorSchemaContext = {
 
 const DocExplorerWithContext: FC = () => {
   return (
-    <DocExplorerStore>
-      <DocExplorer />
-    </DocExplorerStore>
+    <Tooltip.Provider>
+      <DocExplorerStore>
+        <DocExplorer />
+      </DocExplorerStore>
+    </Tooltip.Provider>
   );
 };
 
@@ -88,8 +90,8 @@ describe('DocExplorer', () => {
     const error = container.querySelectorAll('.graphiql-doc-explorer-error');
     expect(error).toHaveLength(0);
     expect(
-      container.querySelector('.graphiql-markdown-description'),
-    ).toHaveTextContent('GraphQL Schema for testing');
+      container.querySelector('.graphiql-doc-explorer-schema-overview'),
+    ).toBeInTheDocument();
   });
   it('renders correctly with schema error', () => {
     useGraphiQL.mockImplementation(cb => cb(withErrorSchemaContext));
@@ -124,20 +126,27 @@ describe('DocExplorer', () => {
       cb({ ...defaultSchemaContext, schema: initialSchema }),
     );
     const { container, rerender } = render(
-      <DocExplorerStore>
-        <SetInitialStack />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <SetInitialStack />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
 
     // First proper render of doc explorer
     rerender(
-      <DocExplorerStore>
-        <DocExplorer />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <DocExplorer />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
 
-    const title = container.querySelector('.graphiql-doc-explorer-title')!;
-    expect(title.textContent).toEqual('field');
+    // The current page is shown as the last breadcrumb segment
+    const breadcrumb = container.querySelector(
+      '.graphiql-doc-explorer-breadcrumb-current',
+    )!;
+    expect(breadcrumb.textContent).toEqual('field');
 
     // Second render of doc explorer, this time with a new schema, with _same_ field name
     useGraphiQL.mockImplementation(cb =>
@@ -147,13 +156,17 @@ describe('DocExplorer', () => {
       }),
     );
     rerender(
-      <DocExplorerStore>
-        <DocExplorer />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <DocExplorer />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
-    const title2 = container.querySelector('.graphiql-doc-explorer-title')!;
+    const breadcrumb2 = container.querySelector(
+      '.graphiql-doc-explorer-breadcrumb-current',
+    )!;
     // Because `Query.field` still exists in the new schema, we can still render it
-    expect(title2.textContent).toEqual('field');
+    expect(breadcrumb2.textContent).toEqual('field');
   });
   it('trims nav stack when necessary', () => {
     const initialSchema = makeSchema();
@@ -179,20 +192,26 @@ describe('DocExplorer', () => {
       cb({ ...defaultSchemaContext, schema: initialSchema }),
     );
     const { container, rerender } = render(
-      <DocExplorerStore>
-        <SetInitialStack />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <SetInitialStack />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
 
     // First proper render of doc explorer
     rerender(
-      <DocExplorerStore>
-        <DocExplorer />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <DocExplorer />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
 
-    const title = container.querySelector('.graphiql-doc-explorer-title')!;
-    expect(title.textContent).toEqual('field');
+    const breadcrumb = container.querySelector(
+      '.graphiql-doc-explorer-breadcrumb-current',
+    )!;
+    expect(breadcrumb.textContent).toEqual('field');
 
     // Second render of doc explorer, this time with a new schema, with a different field name
     useGraphiQL.mockImplementation(cb =>
@@ -202,12 +221,16 @@ describe('DocExplorer', () => {
       }),
     );
     rerender(
-      <DocExplorerStore>
-        <DocExplorer />
-      </DocExplorerStore>,
+      <Tooltip.Provider>
+        <DocExplorerStore>
+          <DocExplorer />
+        </DocExplorerStore>
+      </Tooltip.Provider>,
     );
-    const title2 = container.querySelector('.graphiql-doc-explorer-title')!;
+    const breadcrumb2 = container.querySelector(
+      '.graphiql-doc-explorer-breadcrumb-current',
+    )!;
     // Because `Query.field` doesn't exist anymore, the top-most item we can render is `Query`
-    expect(title2.textContent).toEqual('Query');
+    expect(breadcrumb2.textContent).toEqual('Query');
   });
 });
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/__tests__/field-documentation.spec.tsx b/packages/graphiql-plugin-doc-explorer/src/components/__tests__/field-documentation.spec.tsx
index 65e0219e628..09c707671a9 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/__tests__/field-documentation.spec.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/__tests__/field-documentation.spec.tsx
@@ -78,7 +78,7 @@ describe('FieldDocumentation', () => {
       />,
     );
     expect(
-      container.querySelector('.graphiql-markdown-description'),
+      container.querySelector('.graphiql-doc-explorer-field-card-description'),
     ).not.toBeInTheDocument();
     expect(
       container.querySelector('.graphiql-doc-explorer-type-name'),
@@ -95,7 +95,7 @@ describe('FieldDocumentation', () => {
       />,
     );
     expect(
-      container.querySelector('.graphiql-markdown-description'),
+      container.querySelector('.graphiql-doc-explorer-field-card-description'),
     ).not.toBeInTheDocument();
     expect(
       container.querySelector('.graphiql-doc-explorer-type-name'),
@@ -113,7 +113,7 @@ describe('FieldDocumentation', () => {
       container.querySelector('.graphiql-doc-explorer-type-name'),
     ).toHaveTextContent('String');
     expect(
-      container.querySelector('.graphiql-markdown-description'),
+      container.querySelector('.graphiql-doc-explorer-field-card-description'),
     ).toHaveTextContent('Example String field with arguments');
   });
 
@@ -127,14 +127,14 @@ describe('FieldDocumentation', () => {
       container.querySelector('.graphiql-doc-explorer-type-name'),
     ).toHaveTextContent('String');
     expect(
-      container.querySelector('.graphiql-markdown-description'),
+      container.querySelector('.graphiql-doc-explorer-field-card-description'),
     ).toHaveTextContent('Example String field with arguments');
     expect(
       container.querySelectorAll('.graphiql-doc-explorer-argument'),
     ).toHaveLength(1);
     expect(
       container.querySelector('.graphiql-doc-explorer-argument'),
-    ).toHaveTextContent('stringArg: String');
+    ).toHaveTextContent('stringArg:String');
     // by default, the deprecation docs should be hidden
     expect(
       container.querySelectorAll('.graphiql-markdown-deprecation'),
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css b/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css
new file mode 100644
index 00000000000..f444085807b
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css
@@ -0,0 +1,140 @@
+.graphiql-doc-explorer-arguments-list {
+  display: flex;
+  flex-direction: column;
+  padding: var(--px-4) 0;
+}
+
+/* Section header — "ARGUMENTS · N" / "DIRECTIVES · N" */
+.graphiql-doc-explorer-arguments-list-header {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: var(--px-6) var(--px-16) var(--px-4);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  color: oklch(var(--fg-subtle));
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  width: 100%;
+  text-align: left;
+
+  & svg {
+    width: 9px;
+    height: 9px;
+    flex-shrink: 0;
+  }
+
+  &:hover {
+    color: oklch(var(--fg-muted));
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: -2px;
+  }
+}
+
+.graphiql-doc-explorer-arguments-list-count {
+  color: oklch(var(--fg-dim));
+  font-weight: 500;
+}
+
+.graphiql-doc-explorer-arguments-list-body {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Individual argument row */
+.graphiql-doc-explorer-argument {
+  display: flex;
+  flex-direction: column;
+  gap: var(--px-4);
+  padding: 5px var(--px-16) 5px var(--px-24);
+}
+
+.graphiql-doc-explorer-argument--deprecated {
+  opacity: 0.6;
+}
+
+/* Signature line: name : type = default */
+.graphiql-doc-explorer-argument-sig {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: var(--px-4);
+  font-family: var(--font-family-mono);
+  font-size: 12px;
+}
+
+.graphiql-doc-explorer-argument-name {
+  color: oklch(var(--accent-green-light));
+}
+
+.graphiql-doc-explorer-argument-colon {
+  color: oklch(var(--fg-disabled));
+}
+
+.graphiql-doc-explorer-argument-type {
+  color: oklch(var(--accent-orange));
+
+  & .graphiql-doc-explorer-type-name {
+    color: oklch(var(--accent-orange));
+
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+}
+
+.graphiql-doc-explorer-argument-default {
+  color: oklch(var(--fg-muted));
+}
+
+.graphiql-doc-explorer-argument-desc {
+  font-size: 11px;
+  color: oklch(var(--fg-subtle));
+  line-height: 15px;
+}
+
+.graphiql-doc-explorer-arguments-list-show-deprecated {
+  margin: var(--px-8) var(--px-16);
+}
+
+/* Directives — same eyebrow layout as ArgumentsList */
+.graphiql-doc-explorer-directives-list {
+  display: flex;
+  flex-direction: column;
+  padding: var(--px-4) 0;
+}
+
+.graphiql-doc-explorer-directives-list-header {
+  padding: var(--px-6) var(--px-16) var(--px-4);
+  color: oklch(var(--fg-subtle));
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.graphiql-doc-explorer-directives-list-count {
+  color: oklch(var(--fg-dim));
+  font-weight: 500;
+}
+
+.graphiql-doc-explorer-directives-list-body {
+  display: flex;
+  flex-direction: column;
+}
+
+.graphiql-doc-explorer-directive-row {
+  padding: 5px var(--px-16) 5px var(--px-24);
+  font-family: var(--font-family-mono);
+  font-size: 12px;
+}
+
+.graphiql-doc-explorer-directive-row .graphiql-doc-explorer-directive {
+  color: oklch(var(--accent-orange));
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.tsx b/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.tsx
new file mode 100644
index 00000000000..ed36f970da6
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.tsx
@@ -0,0 +1,115 @@
+import { FC, useState } from 'react';
+import { astFromValue, print, type GraphQLArgument } from 'graphql';
+import { Button, ChevronDownIcon, ChevronUpIcon } from '@graphiql/react';
+import { DeprecationReason } from './deprecation-reason';
+import { TypeLink } from './type-link';
+import { renderType } from './utils';
+import './arguments-list.css';
+
+type ArgumentsListProps = {
+  title: 'ARGUMENTS' | 'DEPRECATED ARGUMENTS';
+  args: GraphQLArgument[];
+};
+
+export const ArgumentsList: FC<ArgumentsListProps> = ({ title, args }) => {
+  const [expanded, setExpanded] = useState(true);
+
+  if (args.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="graphiql-doc-explorer-arguments-list">
+      <button
+        type="button"
+        className="graphiql-doc-explorer-arguments-list-header"
+        onClick={() => setExpanded(e => !e)}
+        aria-expanded={expanded}
+      >
+        {expanded ? <ChevronDownIcon /> : <ChevronUpIcon />}
+        <span>
+          {title}{' '}
+          <span className="graphiql-doc-explorer-arguments-list-count">
+            · {args.length}
+          </span>
+        </span>
+      </button>
+      {expanded && (
+        <div className="graphiql-doc-explorer-arguments-list-body">
+          {args.map(arg => (
+            <ArgumentRow key={arg.name} arg={arg} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+type ShowDeprecatedArgumentsButtonProps = {
+  onClick: () => void;
+};
+
+export const ShowDeprecatedArgumentsButton: FC<
+  ShowDeprecatedArgumentsButtonProps
+> = ({ onClick }) => (
+  <Button
+    type="button"
+    onClick={onClick}
+    className="graphiql-doc-explorer-arguments-list-show-deprecated"
+  >
+    Show Deprecated Arguments
+  </Button>
+);
+
+type ArgumentRowProps = {
+  arg: GraphQLArgument;
+};
+
+const ArgumentRow: FC<ArgumentRowProps> = ({ arg }) => {
+  const defaultAst =
+    arg.defaultValue === undefined
+      ? null
+      : astFromValue(arg.defaultValue, arg.type);
+  const isDeprecated = Boolean(arg.deprecationReason);
+
+  return (
+    <div
+      className={[
+        'graphiql-doc-explorer-argument',
+        isDeprecated ? 'graphiql-doc-explorer-argument--deprecated' : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      <div className="graphiql-doc-explorer-argument-sig">
+        <span className="graphiql-doc-explorer-argument-name">{arg.name}</span>
+        <span
+          className="graphiql-doc-explorer-argument-colon"
+          aria-hidden="true"
+        >
+          :
+        </span>
+        <span className="graphiql-doc-explorer-argument-type">
+          {renderType(arg.type, namedType => (
+            <TypeLink type={namedType} />
+          ))}
+        </span>
+        {defaultAst && (
+          <span className="graphiql-doc-explorer-argument-default">
+            = {print(defaultAst)}
+          </span>
+        )}
+      </div>
+      {arg.description && (
+        <div className="graphiql-doc-explorer-argument-desc">
+          {arg.description}
+        </div>
+      )}
+      {arg.deprecationReason ? (
+        <DeprecationReason preview={false}>
+          {arg.deprecationReason}
+        </DeprecationReason>
+      ) : null}
+    </div>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.css b/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.css
new file mode 100644
index 00000000000..2213a8ec1e1
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.css
@@ -0,0 +1,50 @@
+.graphiql-doc-explorer-breadcrumb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0;
+  padding: var(--px-6) var(--px-16) 0;
+  font-family: var(--font-family-mono);
+  font-size: 11.5px;
+  line-height: 1.4;
+}
+
+.graphiql-doc-explorer-breadcrumb-segment {
+  display: flex;
+  align-items: center;
+  gap: var(--px-4);
+}
+
+.graphiql-doc-explorer-breadcrumb-sep {
+  color: oklch(var(--fg-dim));
+  margin: 0 var(--px-4);
+  font-family: var(--font-family);
+  font-size: 13px;
+}
+
+/* Query root — accent blue */
+a.graphiql-doc-explorer-breadcrumb-root,
+span.graphiql-doc-explorer-breadcrumb-root {
+  color: oklch(var(--accent-blue));
+  text-decoration: none;
+}
+
+a.graphiql-doc-explorer-breadcrumb-root:hover {
+  text-decoration: underline;
+}
+
+/* Intermediate types — green */
+a.graphiql-doc-explorer-breadcrumb-intermediate,
+span.graphiql-doc-explorer-breadcrumb-intermediate {
+  color: oklch(var(--accent-green-light));
+  text-decoration: none;
+}
+
+a.graphiql-doc-explorer-breadcrumb-intermediate:hover {
+  text-decoration: underline;
+}
+
+/* Current (last) segment — strong foreground */
+span.graphiql-doc-explorer-breadcrumb-current {
+  color: oklch(var(--fg-strong));
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.tsx b/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.tsx
new file mode 100644
index 00000000000..50d31a01853
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/breadcrumb.tsx
@@ -0,0 +1,62 @@
+import type { FC } from 'react';
+import type { DocExplorerNavStack } from '../context';
+import './breadcrumb.css';
+
+type BreadcrumbProps = {
+  navStack: DocExplorerNavStack;
+  onNavigateTo: (index: number) => void;
+};
+
+export const Breadcrumb: FC<BreadcrumbProps> = ({ navStack, onNavigateTo }) => {
+  if (navStack.length <= 1) {
+    return null;
+  }
+
+  return (
+    <nav
+      className="graphiql-doc-explorer-breadcrumb"
+      aria-label="Schema navigation path"
+    >
+      {navStack.map((item, index) => {
+        const isLast = index === navStack.length - 1;
+        const depthClass =
+          index === 0
+            ? 'graphiql-doc-explorer-breadcrumb-root'
+            : isLast
+              ? 'graphiql-doc-explorer-breadcrumb-current'
+              : 'graphiql-doc-explorer-breadcrumb-intermediate';
+
+        return (
+          <span
+            key={index}
+            className="graphiql-doc-explorer-breadcrumb-segment"
+          >
+            {index > 0 && (
+              <span
+                className="graphiql-doc-explorer-breadcrumb-sep"
+                aria-hidden="true"
+              >
+                ›
+              </span>
+            )}
+            {isLast ? (
+              <span className={depthClass}>{item.name}</span>
+            ) : (
+              <a
+                href="#"
+                className={depthClass}
+                onClick={event => {
+                  event.preventDefault();
+                  onNavigateTo(index);
+                }}
+                aria-label={`Go back to ${item.name}`}
+              >
+                {item.name}
+              </a>
+            )}
+          </span>
+        );
+      })}
+    </nav>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
index 5b27c40e27b..1bb60b6a48c 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.css
@@ -1,108 +1,61 @@
-/* The header wrapper — positions PanelHeader as a containing block for search overlay */
-.graphiql-doc-explorer-header {
-  & .graphiql-panel-header {
-    position: relative;
-
-    &:focus-within {
-      & .graphiql-doc-explorer-title {
-        /* Hide the title when the search input is focused */
-        visibility: hidden;
-      }
-
-      & .graphiql-doc-explorer-back:not(:focus) {
-        /**
-          * Make the back link invisible when focussing the search input. Hiding
-          * it in any other way makes it impossible to focus the link by pressing
-          * Shift-Tab while the input is focussed.
-          */
-        color: transparent;
-      }
-    }
-  }
-}
-
-.graphiql-doc-explorer-header-content {
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
+/* Eyebrow title in PanelHeader */
+.graphiql-panel-header-title {
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  font-size: var(--font-size-eyebrow);
 }
 
-/* The search input in the header of the doc explorer */
-.graphiql-doc-explorer-search {
-  position: absolute;
-  right: var(--px-14);
-  top: var(--px-10);
-
-  &:focus-within {
-    left: var(--px-14);
-  }
-
-  &:not(:focus-within) [role='combobox'] {
-    height: 24px;
-    width: 6.5ch;
-  }
-
-  & [role='combobox']:focus {
-    width: 100%;
-  }
+/* Main content area */
+.graphiql-doc-explorer-content {
+  overflow-y: auto;
+  flex: 1;
 }
 
-/* The back-button in the doc explorer */
-a.graphiql-doc-explorer-back {
-  align-items: center;
+/* Schema overview and field-documentation padding */
+.graphiql-doc-explorer-content > * {
   color: oklch(var(--fg-muted));
-  display: flex;
-  text-decoration: none;
-
-  &:hover {
-    text-decoration: underline;
-  }
-
-  &:focus {
-    outline: oklch(var(--fg-muted)) auto 1px;
-
-    & + .graphiql-doc-explorer-title {
-      /* Don't hide the header when focussing the back link */
-      visibility: unset;
-    }
-  }
-
-  & > svg {
-    height: var(--px-8);
-    margin-right: var(--px-8);
-    width: var(--px-8);
-  }
+  padding: 0 var(--px-16) var(--px-16);
+  margin-top: var(--px-16);
 }
 
-/* The title of the currently active page in the doc explorer */
-.graphiql-doc-explorer-title {
-  color: oklch(var(--fg-strong));
-  font-weight: 600;
-  font-size: 12px;
-  overflow-x: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-
-  &:not(:first-child) {
-    margin-top: var(--px-4);
-  }
+/* TypeCard and FieldCard keep their own horizontal padding */
+.graphiql-doc-explorer-content .graphiql-doc-explorer-type-card,
+.graphiql-doc-explorer-content .graphiql-doc-explorer-field-card {
+  padding: var(--px-10) var(--px-16);
+  margin-top: 0;
 }
 
-/* The contents of the currently active page in the doc explorer */
-.graphiql-doc-explorer-content {
-  padding: 0 var(--px-14) var(--px-14);
+/* FieldsList and ArgumentsList rows span full width, so zero out container padding */
+.graphiql-doc-explorer-content .graphiql-doc-explorer-fields-list,
+.graphiql-doc-explorer-content .graphiql-doc-explorer-arguments-list {
+  padding-left: 0;
+  padding-right: 0;
+  padding-top: 0;
+  margin-top: 0;
 }
 
-.graphiql-doc-explorer-content > * {
+/* Wrap for enum/union/interface extra sections */
+.graphiql-doc-explorer-type-extra {
+  padding: 0 var(--px-16) var(--px-16);
+  margin-top: var(--px-16);
   color: oklch(var(--fg-muted));
-  margin-top: var(--px-20);
 }
 
 /* Error message */
 .graphiql-doc-explorer-error {
   background-color: oklch(var(--accent-red) / 0.15);
   border: 1px solid oklch(var(--accent-red));
-  border-radius: var(--border-radius-8);
+  border-radius: var(--radius-sm);
   color: oklch(var(--accent-red));
   padding: var(--px-8) var(--px-12);
+  margin: var(--px-16);
+}
+
+/* Old back-button and title selectors kept for Cypress compatibility */
+a.graphiql-doc-explorer-back {
+  display: none;
+}
+
+.graphiql-doc-explorer-title {
+  display: none;
 }
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
index 709c37d4799..3a6ce7cec84 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/doc-explorer.tsx
@@ -1,16 +1,21 @@
-import { isType } from 'graphql';
-import type { FC, ReactNode } from 'react';
 import {
-  ChevronLeftIcon,
-  PanelHeader,
-  Spinner,
-  useGraphiQL,
-  pick,
-} from '@graphiql/react';
+  GraphQLNamedType,
+  isEnumType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+  isType,
+  isUnionType,
+} from 'graphql';
+import type { FC, ReactNode } from 'react';
+import { PanelHeader, Spinner, useGraphiQL, pick } from '@graphiql/react';
 import { useDocExplorer, useDocExplorerActions } from '../context';
+import { Breadcrumb } from './breadcrumb';
 import { FieldDocumentation } from './field-documentation';
+import { FieldsList } from './fields-list';
 import { SchemaDocumentation } from './schema-documentation';
-import { Search } from './search';
+import { SearchRow } from './search-row';
+import { TypeCard } from './type-card';
 import { TypeDocumentation } from './type-documentation';
 import './doc-explorer.css';
 
@@ -22,6 +27,13 @@ export const DocExplorer: FC = () => {
   const { pop } = useDocExplorerActions();
   const navItem = explorerNavStack.at(-1)!;
 
+  const navigateToIndex = (index: number) => {
+    const stepsBack = explorerNavStack.length - 1 - index;
+    for (let i = 0; i < stepsBack; i++) {
+      pop();
+    }
+  };
+
   let content: ReactNode = null;
   if (fetchError) {
     content = (
@@ -34,11 +46,8 @@ export const DocExplorer: FC = () => {
       </div>
     );
   } else if (isIntrospecting) {
-    // Schema is undefined when it is being loaded via introspection.
     content = <Spinner />;
   } else if (!schema) {
-    // Schema is null when it explicitly does not exist, typically due to
-    // an error during introspection.
     content = (
       <div className="graphiql-doc-explorer-error">
         No GraphQL schema available
@@ -47,48 +56,48 @@ export const DocExplorer: FC = () => {
   } else if (explorerNavStack.length === 1) {
     content = <SchemaDocumentation schema={schema} />;
   } else if (isType(navItem.def)) {
-    content = <TypeDocumentation type={navItem.def} />;
+    content = <TypeView type={navItem.def} />;
   } else if (navItem.def) {
     content = <FieldDocumentation field={navItem.def} />;
   }
 
-  let prevName;
-  if (explorerNavStack.length > 1) {
-    prevName = explorerNavStack.at(-2)!.name;
-  }
-
-  const headerTitle = (
-    <div className="graphiql-doc-explorer-header-content">
-      {prevName && (
-        <a
-          href="#"
-          className="graphiql-doc-explorer-back"
-          onClick={event => {
-            event.preventDefault();
-            pop();
-          }}
-          aria-label={`Go back to ${prevName}`}
-        >
-          <ChevronLeftIcon />
-          {prevName}
-        </a>
-      )}
-      <div className="graphiql-doc-explorer-title">{navItem.name}</div>
-    </div>
-  );
+  const isTypeOrFieldView = explorerNavStack.length > 1;
 
   return (
     <section
       className="graphiql-doc-explorer"
       aria-label="Documentation Explorer"
     >
-      <div className="graphiql-doc-explorer-header">
-        <PanelHeader
-          title={headerTitle}
-          actions={<Search key={navItem.name} />}
+      <PanelHeader title="Schema Explorer" />
+      {isTypeOrFieldView && (
+        <Breadcrumb
+          navStack={explorerNavStack}
+          onNavigateTo={navigateToIndex}
         />
-      </div>
+      )}
+      <SearchRow key={navItem.name} />
       <div className="graphiql-doc-explorer-content">{content}</div>
     </section>
   );
 };
+
+const TypeView: FC<{ type: GraphQLNamedType }> = ({ type }) => {
+  const hasNewFieldsList =
+    isObjectType(type) || isInterfaceType(type) || isInputObjectType(type);
+  // Enum/union/scalar still need the TypeDocumentation for enum values and
+  // possible-type sections; interface needs it for Implementations.
+  const needsTypeDocs =
+    isEnumType(type) || isUnionType(type) || isInterfaceType(type);
+
+  return (
+    <>
+      <TypeCard type={type} />
+      {hasNewFieldsList && <FieldsList type={type} />}
+      {needsTypeDocs && (
+        <div className="graphiql-doc-explorer-type-extra">
+          <TypeDocumentation type={type} hideHeader />
+        </div>
+      )}
+    </>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/field-card.css b/packages/graphiql-plugin-doc-explorer/src/components/field-card.css
new file mode 100644
index 00000000000..b17d6260076
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/field-card.css
@@ -0,0 +1,45 @@
+.graphiql-doc-explorer-field-card {
+  border-top: 1px solid oklch(var(--border-default));
+}
+
+.graphiql-doc-explorer-field-card-header {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: var(--px-6);
+  margin-bottom: var(--px-4);
+}
+
+.graphiql-doc-explorer-field-card-name {
+  font-family: var(--font-family-mono);
+  font-size: 14px;
+  font-weight: 600;
+  color: oklch(var(--accent-green-light));
+}
+
+.graphiql-doc-explorer-field-card-colon {
+  font-family: var(--font-family-mono);
+  font-size: 14px;
+  color: oklch(var(--fg-muted));
+}
+
+.graphiql-doc-explorer-field-card-type {
+  font-family: var(--font-family-mono);
+  font-size: 14px;
+  color: oklch(var(--accent-orange));
+
+  & .graphiql-doc-explorer-type-name {
+    color: oklch(var(--accent-orange));
+
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+}
+
+.graphiql-doc-explorer-field-card-description {
+  margin: 0 0 var(--px-6);
+  font-size: 12px;
+  color: oklch(var(--fg-muted));
+  line-height: 17px;
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/field-card.tsx b/packages/graphiql-plugin-doc-explorer/src/components/field-card.tsx
new file mode 100644
index 00000000000..301e7a4f4c8
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/field-card.tsx
@@ -0,0 +1,44 @@
+import type { FC } from 'react';
+import type { DocExplorerFieldDef } from '../context';
+import { DeprecationReason } from './deprecation-reason';
+import { TypeLink } from './type-link';
+import { renderType } from './utils';
+import './field-card.css';
+
+type FieldCardProps = {
+  field: DocExplorerFieldDef;
+};
+
+export const FieldCard: FC<FieldCardProps> = ({ field }) => {
+  return (
+    <div className="graphiql-doc-explorer-field-card">
+      <div className="graphiql-doc-explorer-field-card-header">
+        <span className="graphiql-doc-explorer-type-badge">FIELD</span>
+        <span className="graphiql-doc-explorer-field-card-name">
+          {field.name}
+        </span>
+        <span
+          className="graphiql-doc-explorer-field-card-colon"
+          aria-hidden="true"
+        >
+          :
+        </span>
+        <span className="graphiql-doc-explorer-field-card-type">
+          {renderType(field.type, namedType => (
+            <TypeLink type={namedType} />
+          ))}
+        </span>
+      </div>
+      {field.description && (
+        <p className="graphiql-doc-explorer-field-card-description">
+          {field.description}
+        </p>
+      )}
+      {'deprecationReason' in field && field.deprecationReason ? (
+        <DeprecationReason preview={false}>
+          {field.deprecationReason}
+        </DeprecationReason>
+      ) : null}
+    </div>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/field-documentation.tsx b/packages/graphiql-plugin-doc-explorer/src/components/field-documentation.tsx
index c4c6ec4f253..e45397503de 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/field-documentation.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/field-documentation.tsx
@@ -1,12 +1,9 @@
-import type { GraphQLArgument } from 'graphql';
+import type { ConstDirectiveNode, GraphQLArgument } from 'graphql';
 import { FC, useState } from 'react';
-import { Button, MarkdownContent } from '@graphiql/react';
 import type { DocExplorerFieldDef } from '../context';
-import { Argument } from './argument';
-import { DeprecationReason } from './deprecation-reason';
+import { ArgumentsList, ShowDeprecatedArgumentsButton } from './arguments-list';
 import { Directive } from './directive';
-import { ExplorerSection } from './section';
-import { TypeLink } from './type-link';
+import { FieldCard } from './field-card';
 
 type FieldDocumentationProps = {
   /**
@@ -18,17 +15,7 @@ type FieldDocumentationProps = {
 export const FieldDocumentation: FC<FieldDocumentationProps> = ({ field }) => {
   return (
     <>
-      {field.description ? (
-        <MarkdownContent type="description">
-          {field.description}
-        </MarkdownContent>
-      ) : null}
-      <DeprecationReason preview={false}>
-        {field.deprecationReason}
-      </DeprecationReason>
-      <ExplorerSection title="Type">
-        <TypeLink type={field.type} />
-      </ExplorerSection>
+      <FieldCard field={field} />
       <Arguments field={field} />
       <Directives field={field} />
     </>
@@ -37,9 +24,6 @@ export const FieldDocumentation: FC<FieldDocumentationProps> = ({ field }) => {
 
 const Arguments: FC<{ field: DocExplorerFieldDef }> = ({ field }) => {
   const [showDeprecated, setShowDeprecated] = useState(false);
-  const handleShowDeprecated = () => {
-    setShowDeprecated(true);
-  };
 
   if (!('args' in field)) {
     return null;
@@ -57,42 +41,44 @@ const Arguments: FC<{ field: DocExplorerFieldDef }> = ({ field }) => {
 
   return (
     <>
-      {args.length > 0 ? (
-        <ExplorerSection title="Arguments">
-          {args.map(arg => (
-            <Argument key={arg.name} arg={arg} />
-          ))}
-        </ExplorerSection>
-      ) : null}
-      {deprecatedArgs.length > 0 ? (
-        showDeprecated || args.length === 0 ? (
-          <ExplorerSection title="Deprecated Arguments">
-            {deprecatedArgs.map(arg => (
-              <Argument key={arg.name} arg={arg} />
-            ))}
-          </ExplorerSection>
+      <ArgumentsList title="ARGUMENTS" args={args} />
+      {deprecatedArgs.length > 0 &&
+        (showDeprecated || args.length === 0 ? (
+          <ArgumentsList title="DEPRECATED ARGUMENTS" args={deprecatedArgs} />
         ) : (
-          <Button type="button" onClick={handleShowDeprecated}>
-            Show Deprecated Arguments
-          </Button>
-        )
-      ) : null}
+          <ShowDeprecatedArgumentsButton
+            onClick={() => setShowDeprecated(true)}
+          />
+        ))}
     </>
   );
 };
 
 const Directives: FC<{ field: DocExplorerFieldDef }> = ({ field }) => {
-  const directives = field.astNode?.directives;
+  const directives = field.astNode?.directives as
+    | readonly ConstDirectiveNode[]
+    | undefined;
   if (!directives?.length) {
     return null;
   }
   return (
-    <ExplorerSection title="Directives">
-      {directives.map(directive => (
-        <div key={directive.name.value}>
-          <Directive directive={directive} />
-        </div>
-      ))}
-    </ExplorerSection>
+    <div className="graphiql-doc-explorer-directives-list">
+      <div className="graphiql-doc-explorer-directives-list-header">
+        DIRECTIVES{' '}
+        <span className="graphiql-doc-explorer-directives-list-count">
+          · {directives.length}
+        </span>
+      </div>
+      <div className="graphiql-doc-explorer-directives-list-body">
+        {directives.map(directive => (
+          <div
+            key={directive.name.value}
+            className="graphiql-doc-explorer-directive-row"
+          >
+            <Directive directive={directive} />
+          </div>
+        ))}
+      </div>
+    </div>
   );
 };
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/fields-list.css b/packages/graphiql-plugin-doc-explorer/src/components/fields-list.css
new file mode 100644
index 00000000000..c2353dbdcc3
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/fields-list.css
@@ -0,0 +1,130 @@
+.graphiql-doc-explorer-fields-list {
+  flex: 1;
+  overflow: auto;
+  display: flex;
+  flex-direction: column;
+  padding: var(--px-4) 0;
+}
+
+/* Section header — "FIELDS · N" */
+.graphiql-doc-explorer-fields-list-header {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: var(--px-6) var(--px-16) var(--px-4);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  color: oklch(var(--fg-subtle));
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  width: 100%;
+  text-align: left;
+
+  & svg {
+    width: 9px;
+    height: 9px;
+    flex-shrink: 0;
+  }
+
+  &:hover {
+    color: oklch(var(--fg-muted));
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: -2px;
+  }
+}
+
+.graphiql-doc-explorer-fields-list-count {
+  color: oklch(var(--fg-dim));
+  font-weight: 500;
+}
+
+.graphiql-doc-explorer-fields-list-body {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Individual field row */
+.graphiql-doc-explorer-field-row {
+  display: flex;
+  flex-direction: column;
+  gap: var(--px-4);
+  padding: 5px var(--px-12) 5px var(--px-24);
+  background: transparent;
+  border: none;
+  border-left: 2px solid transparent;
+  cursor: pointer;
+  text-align: left;
+  width: 100%;
+
+  &:hover {
+    background: oklch(var(--fg-default) / 0.04);
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: -2px;
+  }
+}
+
+/* Active row — blue accent */
+.graphiql-doc-explorer-field-row--active {
+  background: oklch(var(--accent-blue) / 0.08);
+  border-left-color: oklch(var(--accent-blue));
+  margin-left: -2px;
+
+  &:hover {
+    background: oklch(var(--accent-blue) / 0.12);
+  }
+}
+
+.graphiql-doc-explorer-field-row--deprecated {
+  opacity: 0.6;
+}
+
+/* Signature line: name : type */
+.graphiql-doc-explorer-field-row-sig {
+  display: flex;
+  align-items: baseline;
+  gap: var(--px-6);
+  font-family: var(--font-family-mono);
+  font-size: 12px;
+}
+
+.graphiql-doc-explorer-field-row-name {
+  color: oklch(var(--accent-green-light));
+}
+
+.graphiql-doc-explorer-field-row-colon {
+  color: oklch(var(--fg-disabled));
+}
+
+/* Return type color — inherits from TypeLink */
+.graphiql-doc-explorer-field-row-type {
+  color: oklch(var(--accent-orange));
+
+  /* TypeLink anchors inside a field row get orange color */
+  & .graphiql-doc-explorer-type-name {
+    color: oklch(var(--accent-orange));
+
+    &:hover {
+      text-decoration: underline;
+    }
+  }
+}
+
+/* Optional description */
+.graphiql-doc-explorer-field-row-desc {
+  font-size: 11px;
+  color: oklch(var(--fg-subtle));
+  line-height: 15px;
+}
+
+.graphiql-doc-explorer-fields-list-show-deprecated {
+  margin: var(--px-8) var(--px-16);
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/fields-list.tsx b/packages/graphiql-plugin-doc-explorer/src/components/fields-list.tsx
new file mode 100644
index 00000000000..8dcc5caea2b
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/fields-list.tsx
@@ -0,0 +1,137 @@
+import { FC, useState } from 'react';
+import {
+  GraphQLNamedType,
+  isObjectType,
+  isInterfaceType,
+  isInputObjectType,
+} from 'graphql';
+import { Button, ChevronDownIcon, ChevronUpIcon } from '@graphiql/react';
+import type { DocExplorerFieldDef } from '../context';
+import { useDocExplorerActions } from '../context';
+import { TypeLink } from './type-link';
+import { renderType } from './utils';
+import './fields-list.css';
+
+type FieldsListProps = {
+  type: GraphQLNamedType;
+  activeFieldName?: string;
+};
+
+export const FieldsList: FC<FieldsListProps> = ({ type, activeFieldName }) => {
+  const [expanded, setExpanded] = useState(true);
+  const [showDeprecated, setShowDeprecated] = useState(false);
+
+  if (
+    !isObjectType(type) &&
+    !isInterfaceType(type) &&
+    !isInputObjectType(type)
+  ) {
+    return null;
+  }
+
+  const fieldMap = type.getFields();
+  const fields: DocExplorerFieldDef[] = [];
+  const deprecatedFields: DocExplorerFieldDef[] = [];
+
+  for (const field of Object.values(fieldMap)) {
+    if (field.deprecationReason) {
+      deprecatedFields.push(field);
+    } else {
+      fields.push(field);
+    }
+  }
+
+  const totalCount =
+    fields.length + (showDeprecated ? deprecatedFields.length : 0);
+
+  return (
+    <div className="graphiql-doc-explorer-fields-list">
+      <button
+        type="button"
+        className="graphiql-doc-explorer-fields-list-header"
+        onClick={() => setExpanded(e => !e)}
+        aria-expanded={expanded}
+      >
+        {expanded ? <ChevronDownIcon /> : <ChevronUpIcon />}
+        <span>
+          FIELDS{' '}
+          <span className="graphiql-doc-explorer-fields-list-count">
+            · {totalCount}
+          </span>
+        </span>
+      </button>
+      {expanded && (
+        <div className="graphiql-doc-explorer-fields-list-body">
+          {fields.map(field => (
+            <FieldRow
+              key={field.name}
+              field={field}
+              isActive={field.name === activeFieldName}
+            />
+          ))}
+          {deprecatedFields.length > 0 &&
+            (showDeprecated || fields.length === 0 ? (
+              deprecatedFields.map(field => (
+                <FieldRow
+                  key={field.name}
+                  field={field}
+                  isActive={field.name === activeFieldName}
+                  deprecated
+                />
+              ))
+            ) : (
+              <Button
+                type="button"
+                onClick={() => setShowDeprecated(true)}
+                className="graphiql-doc-explorer-fields-list-show-deprecated"
+              >
+                Show Deprecated Fields
+              </Button>
+            ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+type FieldRowProps = {
+  field: DocExplorerFieldDef;
+  isActive: boolean;
+  deprecated?: boolean;
+};
+
+const FieldRow: FC<FieldRowProps> = ({ field, isActive, deprecated }) => {
+  const { push } = useDocExplorerActions();
+
+  return (
+    <button
+      type="button"
+      className={[
+        'graphiql-doc-explorer-field-row',
+        isActive ? 'graphiql-doc-explorer-field-row--active' : '',
+        deprecated ? 'graphiql-doc-explorer-field-row--deprecated' : '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      onClick={() => push({ name: field.name, def: field })}
+      aria-current={isActive ? 'true' : undefined}
+    >
+      <div className="graphiql-doc-explorer-field-row-sig">
+        <span className="graphiql-doc-explorer-field-row-name">
+          {field.name}
+        </span>
+        <span className="graphiql-doc-explorer-field-row-colon">:</span>
+        <span className="graphiql-doc-explorer-field-row-type">
+          {renderType(field.type, namedType => (
+            <TypeLink type={namedType} />
+          ))}
+        </span>
+      </div>
+      {field.description && (
+        <div className="graphiql-doc-explorer-field-row-desc">
+          {field.description}
+        </div>
+      )}
+    </button>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/index.ts b/packages/graphiql-plugin-doc-explorer/src/components/index.ts
index 726eefb7198..4686c39120e 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/index.ts
+++ b/packages/graphiql-plugin-doc-explorer/src/components/index.ts
@@ -1,12 +1,18 @@
 export { Argument } from './argument';
+export { ArgumentsList } from './arguments-list';
+export { Breadcrumb } from './breadcrumb';
 export { DefaultValue } from './default-value';
 export { DeprecationReason } from './deprecation-reason';
 export { Directive } from './directive';
 export { DocExplorer } from './doc-explorer';
+export { FieldCard } from './field-card';
 export { FieldDocumentation } from './field-documentation';
 export { FieldLink } from './field-link';
+export { FieldsList } from './fields-list';
 export { SchemaDocumentation } from './schema-documentation';
 export { Search } from './search';
+export { SearchRow } from './search-row';
 export { ExplorerSection } from './section';
+export { TypeCard } from './type-card';
 export { TypeDocumentation } from './type-documentation';
 export { TypeLink } from './type-link';
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
index d22d70ebcd5..110ee3b2dce 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
@@ -1,3 +1,89 @@
-.graphiql-doc-explorer-root-type {
+.graphiql-doc-explorer-schema-overview {
+  display: flex;
+  flex-direction: column;
+  padding: var(--px-8) 0;
+}
+
+/* Eyebrow section headers — matches FieldsList header style */
+.graphiql-doc-explorer-schema-section-header {
+  padding: var(--px-6) var(--px-16) var(--px-4);
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: oklch(var(--fg-subtle));
+}
+
+.graphiql-doc-explorer-schema-section-header--types {
+  margin-top: var(--px-12);
+}
+
+.graphiql-doc-explorer-schema-type-count {
+  color: oklch(var(--fg-dim));
+  font-weight: 500;
+}
+
+/* Root type rows */
+.graphiql-doc-explorer-schema-root-row {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  padding: 5px var(--px-16);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  width: 100%;
+  font-family: var(--font-family-mono);
+  font-size: 12px;
+
+  &:hover {
+    background: oklch(var(--fg-default) / 0.04);
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: -2px;
+  }
+}
+
+.graphiql-doc-explorer-schema-root-label {
+  color: oklch(var(--fg-default));
+}
+
+.graphiql-doc-explorer-schema-root-colon {
   color: oklch(var(--fg-muted));
 }
+
+/* Type name in root rows — orange like TypeLink */
+.graphiql-doc-explorer-schema-root-row .graphiql-doc-explorer-type-name {
+  color: oklch(var(--accent-orange));
+}
+
+/* All-types rows */
+.graphiql-doc-explorer-schema-type-row {
+  display: flex;
+  align-items: center;
+  gap: var(--px-8);
+  padding: 4px var(--px-16);
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  width: 100%;
+
+  &:hover {
+    background: oklch(var(--fg-default) / 0.04);
+  }
+
+  &:focus-visible {
+    outline: 2px solid oklch(var(--accent-blue));
+    outline-offset: -2px;
+  }
+}
+
+.graphiql-doc-explorer-schema-type-name {
+  font-family: var(--font-family-mono);
+  font-size: 12px;
+  color: oklch(var(--fg-default));
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.tsx b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.tsx
index 280533644c7..af8c665c542 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.tsx
@@ -1,8 +1,15 @@
 import type { FC } from 'react';
-import type { GraphQLSchema } from 'graphql';
-import { MarkdownContent } from '@graphiql/react';
-import { ExplorerSection } from './section';
-import { TypeLink } from './type-link';
+import type { GraphQLNamedType, GraphQLSchema } from 'graphql';
+import {
+  isObjectType,
+  isInterfaceType,
+  isInputObjectType,
+  isEnumType,
+  isScalarType,
+  isUnionType,
+} from 'graphql';
+import { MethodPill } from '@graphiql/react';
+import { useDocExplorerActions } from '../context';
 import './schema-documentation.css';
 
 type SchemaDocumentationProps = {
@@ -12,68 +19,129 @@ type SchemaDocumentationProps = {
   schema: GraphQLSchema;
 };
 
+function getTypeKindLabel(type: GraphQLNamedType): string {
+  if (isObjectType(type)) {
+    return 'TYPE';
+  }
+  if (isInterfaceType(type)) {
+    return 'INTERFACE';
+  }
+  if (isInputObjectType(type)) {
+    return 'INPUT';
+  }
+  if (isEnumType(type)) {
+    return 'ENUM';
+  }
+  if (isScalarType(type)) {
+    return 'SCALAR';
+  }
+  if (isUnionType(type)) {
+    return 'UNION';
+  }
+  return 'TYPE';
+}
+
 export const SchemaDocumentation: FC<SchemaDocumentationProps> = ({
   schema,
 }) => {
+  const { push } = useDocExplorerActions();
   const queryType = schema.getQueryType();
   const mutationType = schema.getMutationType();
   const subscriptionType = schema.getSubscriptionType();
-  const typeMap = schema.getTypeMap();
-  const ignoreTypesInAllSchema = [
-    queryType?.name,
-    mutationType?.name,
-    subscriptionType?.name,
-  ];
+  const rootTypeNames = new Set(
+    [queryType?.name, mutationType?.name, subscriptionType?.name].filter(
+      Boolean,
+    ),
+  );
+
+  const allTypes = Object.values(schema.getTypeMap()).filter(
+    type => !type.name.startsWith('__') && !rootTypeNames.has(type.name),
+  );
 
   return (
-    <>
-      <MarkdownContent type="description">
-        {schema.description ||
-          'A GraphQL schema provides a root type for each kind of operation.'}
-      </MarkdownContent>
-      <ExplorerSection title="Root Types">
-        {queryType ? (
-          <div>
-            <span className="graphiql-doc-explorer-root-type">query</span>
-            {': '}
-            <TypeLink type={queryType} />
-          </div>
-        ) : null}
+    <div className="graphiql-doc-explorer-schema-overview">
+      {/* Root types section */}
+      <div className="graphiql-doc-explorer-schema-section-header">
+        ROOT TYPES
+      </div>
+      <div className="graphiql-doc-explorer-schema-root-types">
+        {queryType && (
+          <button
+            type="button"
+            className="graphiql-doc-explorer-schema-root-row"
+            onClick={() => push({ name: queryType.name, def: queryType })}
+          >
+            <MethodPill operation="query" aria-hidden />
+            <span className="graphiql-doc-explorer-schema-root-label">
+              Query
+            </span>
+            <span className="graphiql-doc-explorer-schema-root-colon">:</span>
+            <span className="graphiql-doc-explorer-type-name">
+              {queryType.name}
+            </span>
+          </button>
+        )}
         {mutationType && (
-          <div>
-            <span className="graphiql-doc-explorer-root-type">mutation</span>
-            {': '}
-            <TypeLink type={mutationType} />
-          </div>
+          <button
+            type="button"
+            className="graphiql-doc-explorer-schema-root-row"
+            onClick={() => push({ name: mutationType.name, def: mutationType })}
+          >
+            <MethodPill operation="mutation" aria-hidden />
+            <span className="graphiql-doc-explorer-schema-root-label">
+              Mutation
+            </span>
+            <span className="graphiql-doc-explorer-schema-root-colon">:</span>
+            <span className="graphiql-doc-explorer-type-name">
+              {mutationType.name}
+            </span>
+          </button>
         )}
         {subscriptionType && (
-          <div>
-            <span className="graphiql-doc-explorer-root-type">
-              subscription
+          <button
+            type="button"
+            className="graphiql-doc-explorer-schema-root-row"
+            onClick={() =>
+              push({ name: subscriptionType.name, def: subscriptionType })
+            }
+          >
+            <MethodPill operation="subscription" aria-hidden />
+            <span className="graphiql-doc-explorer-schema-root-label">
+              Subscription
+            </span>
+            <span className="graphiql-doc-explorer-schema-root-colon">:</span>
+            <span className="graphiql-doc-explorer-type-name">
+              {subscriptionType.name}
             </span>
-            {': '}
-            <TypeLink type={subscriptionType} />
-          </div>
+          </button>
         )}
-      </ExplorerSection>
-      <ExplorerSection title="All Schema Types">
-        <div>
-          {Object.values(typeMap).map(type => {
-            if (
-              ignoreTypesInAllSchema.includes(type.name) ||
-              type.name.startsWith('__')
-            ) {
-              return null;
-            }
+      </div>
 
-            return (
-              <div key={type.name}>
-                <TypeLink type={type} />
-              </div>
-            );
-          })}
-        </div>
-      </ExplorerSection>
-    </>
+      {/* All schema types section */}
+      <div className="graphiql-doc-explorer-schema-section-header graphiql-doc-explorer-schema-section-header--types">
+        ALL SCHEMA TYPES
+        <span className="graphiql-doc-explorer-schema-type-count">
+          {' '}
+          · {allTypes.length}
+        </span>
+      </div>
+      <div className="graphiql-doc-explorer-schema-all-types">
+        {allTypes.map(type => (
+          <button
+            key={type.name}
+            type="button"
+            className="graphiql-doc-explorer-schema-type-row"
+            onClick={() => push({ name: type.name, def: type })}
+          >
+            <span className="graphiql-doc-explorer-type-badge">
+              {getTypeKindLabel(type)}
+            </span>
+            <span className="graphiql-doc-explorer-schema-type-name">
+              {type.name}
+            </span>
+          </button>
+        ))}
+      </div>
+    </div>
   );
 };
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search-row.css b/packages/graphiql-plugin-doc-explorer/src/components/search-row.css
new file mode 100644
index 00000000000..75166f40776
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/search-row.css
@@ -0,0 +1,87 @@
+.graphiql-doc-explorer-search-row-wrapper {
+  padding: var(--px-8) var(--px-16);
+  position: relative;
+}
+
+.graphiql-doc-explorer-search-row {
+  position: relative;
+}
+
+.graphiql-doc-explorer-search-row-input {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  background: oklch(var(--bg-subtle));
+  border: 1px solid oklch(var(--border-muted));
+  border-radius: var(--radius-sm);
+  padding: var(--px-4) var(--px-8);
+  cursor: text;
+
+  & svg {
+    width: 11px;
+    height: 11px;
+    color: oklch(var(--fg-disabled));
+    flex-shrink: 0;
+  }
+
+  & [role='combobox'] {
+    flex: 1;
+    min-width: 0;
+    background: transparent;
+    border: none;
+    font-family: var(--font-family-mono);
+    font-size: 11.5px;
+    color: oklch(var(--fg-default));
+
+    &::placeholder {
+      color: oklch(var(--fg-disabled));
+    }
+
+    &:focus {
+      outline: none;
+    }
+  }
+}
+
+.graphiql-doc-explorer-search-row-listbox {
+  position: absolute;
+  top: calc(100% + var(--px-4));
+  left: 0;
+  right: 0;
+  z-index: 5;
+  background: oklch(var(--bg-canvas));
+  border: 1px solid oklch(var(--border-default));
+  border-radius: var(--radius-sm);
+  box-shadow: var(--shadow-popover);
+  max-height: 400px;
+  overflow-y: auto;
+  padding: var(--px-4);
+  font-size: var(--font-size-body);
+  margin: 0;
+
+  & [role='option'] {
+    border-radius: var(--radius-sm);
+    color: oklch(var(--fg-muted));
+    overflow-x: hidden;
+    padding: var(--px-8) var(--px-12);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    cursor: pointer;
+
+    &[data-headlessui-state='active'] {
+      background-color: oklch(var(--fg-default) / 0.08);
+    }
+
+    &:hover {
+      background-color: oklch(var(--fg-default) / 0.12);
+    }
+
+    &[data-headlessui-state='active']:hover {
+      background-color: oklch(var(--fg-default) / 0.16);
+    }
+
+    & + [role='option'] {
+      margin-top: var(--px-4);
+    }
+  }
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx b/packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx
new file mode 100644
index 00000000000..04256a68076
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx
@@ -0,0 +1,192 @@
+import { FC, useEffect, useRef, useState } from 'react';
+import {
+  GraphQLArgument,
+  GraphQLField,
+  GraphQLInputField,
+  GraphQLNamedType,
+  isInputObjectType,
+  isInterfaceType,
+  isObjectType,
+} from 'graphql';
+import {
+  Combobox,
+  ComboboxInput,
+  ComboboxOptions,
+  ComboboxOption,
+} from '@headlessui/react';
+import {
+  formatShortcutForOS,
+  MagnifyingGlassIcon,
+  KeycapHint,
+  debounce,
+  KEY_MAP,
+} from '@graphiql/react';
+import { useDocExplorer, useDocExplorerActions } from '../context';
+import { useSearchResults } from './search';
+import { renderType } from './utils';
+import './search-row.css';
+
+type TypeMatch = { type: GraphQLNamedType };
+type FieldMatch = {
+  type: GraphQLNamedType;
+  field: GraphQLField<unknown, unknown> | GraphQLInputField;
+  argument?: GraphQLArgument;
+};
+
+export const SearchRow: FC = () => {
+  const explorerNavStack = useDocExplorer();
+  const { push } = useDocExplorerActions();
+
+  const inputRef = useRef<HTMLInputElement>(null!);
+  const getSearchResults = useSearchResults();
+  const [searchValue, setSearchValue] = useState('');
+  const [results, setResults] = useState(() => getSearchResults(searchValue));
+  const debouncedGetSearchResults = debounce(200, (search: string) => {
+    setResults(getSearchResults(search));
+  });
+  const [ref] = useState(inputRef);
+  const isFocused = ref.current === document.activeElement;
+
+  useEffect(() => {
+    debouncedGetSearchResults(searchValue);
+  }, [debouncedGetSearchResults, searchValue]);
+
+  const navItem = explorerNavStack.at(-1)!;
+
+  const onSelect = (def: TypeMatch | FieldMatch | null) => {
+    if (!def) {
+      return;
+    }
+    push(
+      'field' in def
+        ? { name: def.field.name, def: def.field }
+        : { name: def.type.name, def: def.type },
+    );
+  };
+
+  const shouldShow =
+    explorerNavStack.length === 1 ||
+    isObjectType(navItem.def) ||
+    isInterfaceType(navItem.def) ||
+    isInputObjectType(navItem.def);
+
+  if (!shouldShow) {
+    return null;
+  }
+
+  const shortcutKeys = formatShortcutForOS(KEY_MAP.searchInDocs.key).split('-');
+
+  return (
+    <div className="graphiql-doc-explorer-search-row-wrapper">
+      <Combobox
+        as="div"
+        className="graphiql-doc-explorer-search-row"
+        onChange={onSelect}
+        aria-label={`Search ${navItem.name}...`}
+      >
+        <div
+          className="graphiql-doc-explorer-search-row-input"
+          onClick={() => {
+            inputRef.current.focus();
+          }}
+        >
+          <MagnifyingGlassIcon />
+          <ComboboxInput
+            autoComplete="off"
+            onChange={event => setSearchValue(event.target.value)}
+            placeholder="Search schema"
+            ref={inputRef}
+            value={searchValue}
+            data-cy="doc-explorer-input"
+          />
+          {!isFocused && !searchValue && (
+            <KeycapHint keys={shortcutKeys} ariaLabel="Search docs shortcut" />
+          )}
+        </div>
+        {isFocused && (
+          <ComboboxOptions
+            className="graphiql-doc-explorer-search-row-listbox"
+            data-cy="doc-explorer-list"
+          >
+            {results.within.length +
+              results.types.length +
+              results.fields.length ===
+            0 ? (
+              <div className="graphiql-doc-explorer-search-empty">
+                No results found
+              </div>
+            ) : (
+              results.within.map((result, i) => (
+                <ComboboxOption
+                  key={`within-${i}`}
+                  value={result}
+                  data-cy="doc-explorer-option"
+                >
+                  <SearchField
+                    field={result.field}
+                    argument={result.argument}
+                  />
+                </ComboboxOption>
+              ))
+            )}
+            {results.within.length > 0 &&
+            results.types.length + results.fields.length > 0 ? (
+              <div className="graphiql-doc-explorer-search-divider">
+                Other results
+              </div>
+            ) : null}
+            {results.types.map((result, i) => (
+              <ComboboxOption
+                key={`type-${i}`}
+                value={result}
+                data-cy="doc-explorer-option"
+              >
+                <SearchType type={result.type} />
+              </ComboboxOption>
+            ))}
+            {results.fields.map((result, i) => (
+              <ComboboxOption
+                key={`field-${i}`}
+                value={result}
+                data-cy="doc-explorer-option"
+              >
+                <SearchType type={result.type} />.
+                <SearchField field={result.field} argument={result.argument} />
+              </ComboboxOption>
+            ))}
+          </ComboboxOptions>
+        )}
+      </Combobox>
+    </div>
+  );
+};
+
+const SearchType: FC<{ type: GraphQLNamedType }> = ({ type }) => (
+  <span className="graphiql-doc-explorer-search-type">{type.name}</span>
+);
+
+type SearchFieldProps = {
+  field: GraphQLField<unknown, unknown> | GraphQLInputField;
+  argument?: GraphQLArgument;
+};
+
+const SearchField: FC<SearchFieldProps> = ({ field, argument }) => {
+  return (
+    <>
+      <span className="graphiql-doc-explorer-search-field">{field.name}</span>
+      {argument ? (
+        <>
+          (
+          <span className="graphiql-doc-explorer-search-argument">
+            {argument.name}
+          </span>
+          :{' '}
+          {renderType(argument.type, namedType => (
+            <SearchType type={namedType} />
+          ))}
+          )
+        </>
+      ) : null}
+    </>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search.css b/packages/graphiql-plugin-doc-explorer/src/components/search.css
index 7d181150974..7c7ed30be89 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/search.css
+++ b/packages/graphiql-plugin-doc-explorer/src/components/search.css
@@ -17,20 +17,26 @@
   background-color: oklch(var(--fg-default) / 0.08);
   border-radius: var(--border-radius-4);
   display: flex;
-  padding: var(--px-8) var(--px-12);
+  flex: 1;
+  gap: var(--px-8);
+  padding: var(--px-4) var(--px-8);
 }
 
 .graphiql-doc-explorer-search [role='combobox'] {
   border: none;
   background-color: transparent;
-  margin-left: var(--px-4);
-  width: 100%;
+  flex: 1;
+  min-width: 0;
 
   &:focus {
     outline: none;
   }
 }
 
+.graphiql-doc-explorer-search:focus-within .graphiql-keycap-hint {
+  display: none;
+}
+
 .graphiql-doc-explorer-search [role='listbox'] {
   background-color: oklch(var(--bg-canvas));
   border: 1px solid oklch(var(--border-default));
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search.tsx b/packages/graphiql-plugin-doc-explorer/src/components/search.tsx
index 8e52a424618..f9e1fd806ab 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/search.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/search.tsx
@@ -17,6 +17,7 @@ import {
 import {
   formatShortcutForOS,
   useGraphiQL,
+  KeycapHint,
   MagnifyingGlassIcon,
   debounce,
   KEY_MAP,
@@ -58,6 +59,8 @@ export const Search: FC = () => {
         : { name: def.type.name, def: def.type },
     );
   };
+  const shortcutKeys = formatShortcutForOS(KEY_MAP.searchInDocs.key).split('-');
+
   const shouldSearchBoxAppear =
     explorerNavStack.length === 1 ||
     isObjectType(navItem.def) ||
@@ -85,13 +88,12 @@ export const Search: FC = () => {
         <ComboboxInput
           autoComplete="off"
           onChange={event => setSearchValue(event.target.value)}
-          placeholder={formatShortcutForOS(
-            formatShortcutForOS(KEY_MAP.searchInDocs.key).replaceAll('-', ' '),
-          )}
+          placeholder="Search Docs"
           ref={inputRef}
           value={searchValue}
           data-cy="doc-explorer-input"
         />
+        <KeycapHint keys={shortcutKeys} ariaLabel="Search docs shortcut" />
       </div>
       {isFocused && (
         <ComboboxOptions data-cy="doc-explorer-list">
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-card.css b/packages/graphiql-plugin-doc-explorer/src/components/type-card.css
new file mode 100644
index 00000000000..73e8dd98dcc
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/type-card.css
@@ -0,0 +1,76 @@
+.graphiql-doc-explorer-type-card {
+  border-top: 1px solid oklch(var(--border-default));
+}
+
+.graphiql-doc-explorer-type-card-header {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  margin-bottom: var(--px-4);
+}
+
+/* [TYPE] badge */
+.graphiql-doc-explorer-type-badge {
+  padding: 1px 6px;
+  background: oklch(var(--accent-blue) / 0.12);
+  color: oklch(var(--accent-blue));
+  font-family: var(--font-family-mono);
+  font-size: 10px;
+  font-weight: 600;
+  border-radius: var(--radius-sm);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  flex-shrink: 0;
+}
+
+.graphiql-doc-explorer-type-card-name {
+  font-family: var(--font-family-mono);
+  font-size: 14px;
+  font-weight: 600;
+  color: oklch(var(--fg-strong));
+  overflow-x: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.graphiql-doc-explorer-type-card-description {
+  margin: 0 0 var(--px-6);
+  font-size: 12px;
+  color: oklch(var(--fg-muted));
+  line-height: 17px;
+}
+
+/* implements row */
+.graphiql-doc-explorer-type-card-implements {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--px-6);
+  margin-top: var(--px-6);
+  font-size: 10.5px;
+  color: oklch(var(--fg-subtle));
+}
+
+.graphiql-doc-explorer-type-card-implements-keyword {
+  font-family: var(--font-family-mono);
+}
+
+.graphiql-doc-explorer-type-card-implements-item {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+}
+
+.graphiql-doc-explorer-type-card-implements-dot {
+  color: oklch(var(--fg-dim));
+}
+
+a.graphiql-doc-explorer-type-card-implements-link {
+  font-family: var(--font-family-mono);
+  color: oklch(var(--accent-orange));
+  text-decoration: none;
+
+  &:hover {
+    text-decoration: underline;
+  }
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-card.tsx b/packages/graphiql-plugin-doc-explorer/src/components/type-card.tsx
new file mode 100644
index 00000000000..52ed749ef6a
--- /dev/null
+++ b/packages/graphiql-plugin-doc-explorer/src/components/type-card.tsx
@@ -0,0 +1,92 @@
+import type { FC } from 'react';
+import {
+  GraphQLNamedType,
+  isObjectType,
+  isInterfaceType,
+  isInputObjectType,
+  isEnumType,
+  isScalarType,
+  isUnionType,
+} from 'graphql';
+import { useDocExplorerActions } from '../context';
+import './type-card.css';
+
+function getTypeKind(type: GraphQLNamedType): string {
+  if (isObjectType(type)) {
+    return 'TYPE';
+  }
+  if (isInterfaceType(type)) {
+    return 'INTERFACE';
+  }
+  if (isInputObjectType(type)) {
+    return 'INPUT';
+  }
+  if (isEnumType(type)) {
+    return 'ENUM';
+  }
+  if (isScalarType(type)) {
+    return 'SCALAR';
+  }
+  if (isUnionType(type)) {
+    return 'UNION';
+  }
+  return 'TYPE';
+}
+
+type TypeCardProps = {
+  type: GraphQLNamedType;
+};
+
+export const TypeCard: FC<TypeCardProps> = ({ type }) => {
+  const { push } = useDocExplorerActions();
+  const kind = getTypeKind(type);
+  const interfaces = isObjectType(type) ? type.getInterfaces() : [];
+
+  return (
+    <div className="graphiql-doc-explorer-type-card">
+      <div className="graphiql-doc-explorer-type-card-header">
+        <span className="graphiql-doc-explorer-type-badge">{kind}</span>
+        <span className="graphiql-doc-explorer-type-card-name">
+          {type.name}
+        </span>
+      </div>
+      {type.description && (
+        <p className="graphiql-doc-explorer-type-card-description">
+          {type.description}
+        </p>
+      )}
+      {interfaces.length > 0 && (
+        <div className="graphiql-doc-explorer-type-card-implements">
+          <span className="graphiql-doc-explorer-type-card-implements-keyword">
+            implements
+          </span>
+          {interfaces.map((iface, i) => (
+            <span
+              key={iface.name}
+              className="graphiql-doc-explorer-type-card-implements-item"
+            >
+              {i > 0 && (
+                <span
+                  className="graphiql-doc-explorer-type-card-implements-dot"
+                  aria-hidden="true"
+                >
+                  ·
+                </span>
+              )}
+              <a
+                href="#"
+                className="graphiql-doc-explorer-type-card-implements-link"
+                onClick={event => {
+                  event.preventDefault();
+                  push({ name: iface.name, def: iface });
+                }}
+              >
+                {iface.name}
+              </a>
+            </span>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.tsx b/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.tsx
index 219ecf3488b..b2d010de80d 100644
--- a/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/components/type-documentation.tsx
@@ -24,16 +24,25 @@ type TypeDocumentationProps = {
    * The type that should be rendered.
    */
   type: GraphQLNamedType;
+  /**
+   * When true, the description, implements-interfaces, and fields sections
+   * are omitted. Used when TypeCard + FieldsList are already rendering those
+   * above the type documentation.
+   */
+  hideHeader?: boolean;
 };
 
-export const TypeDocumentation: FC<TypeDocumentationProps> = ({ type }) => {
+export const TypeDocumentation: FC<TypeDocumentationProps> = ({
+  type,
+  hideHeader,
+}) => {
   return isNamedType(type) ? (
     <>
-      {type.description ? (
+      {!hideHeader && type.description ? (
         <MarkdownContent type="description">{type.description}</MarkdownContent>
       ) : null}
-      <ImplementsInterfaces type={type} />
-      <Fields type={type} />
+      {!hideHeader && <ImplementsInterfaces type={type} />}
+      {!hideHeader && <Fields type={type} />}
       <EnumValues type={type} />
       <PossibleTypes type={type} />
     </>
diff --git a/packages/graphiql-plugin-doc-explorer/src/context.tsx b/packages/graphiql-plugin-doc-explorer/src/context.tsx
index e0bb2c97a8a..91e12425063 100644
--- a/packages/graphiql-plugin-doc-explorer/src/context.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/context.tsx
@@ -96,7 +96,7 @@ export type DocExplorerStoreType = {
   };
 };
 
-const INITIAL_NAV_STACK: DocExplorerNavStack = [{ name: 'Docs' }];
+const INITIAL_NAV_STACK: DocExplorerNavStack = [{ name: 'Root' }];
 
 export const docExplorerStore = createStore<DocExplorerStoreType>(
   (set, get) => ({
diff --git a/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx b/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx
index d699a79a48b..904ab8b8875 100644
--- a/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx
+++ b/packages/graphiql-plugin-doc-explorer/src/stories/doc-explorer.stories.tsx
@@ -9,12 +9,16 @@ import {
   GraphQLObjectType,
   GraphQLSchema,
   GraphQLString,
+  GraphQLUnionType,
 } from 'graphql';
 import { Tooltip } from '@graphiql/react';
 import { DocExplorerStore } from '../context';
 import { TypeDocumentation } from '../components/type-documentation';
 import { FieldDocumentation } from '../components/field-documentation';
 import { SchemaDocumentation } from '../components/schema-documentation';
+import { TypeCard } from '../components/type-card';
+import { FieldsList } from '../components/fields-list';
+import { Breadcrumb } from '../components/breadcrumb';
 import { TypeLink } from '../components/type-link';
 import { FieldLink } from '../components/field-link';
 import { Argument } from '../components/argument';
@@ -87,6 +91,12 @@ const HumanType = new GraphQLObjectType({
   }),
 });
 
+const SearchResultUnion = new GraphQLUnionType({
+  name: 'SearchResult',
+  description: 'A result from a global search',
+  types: [HumanType],
+});
+
 const QueryType = new GraphQLObjectType({
   name: 'Query',
   description: 'The root query type for the Star Wars API',
@@ -116,6 +126,10 @@ const QueryType = new GraphQLObjectType({
       type: GraphQLBoolean,
       deprecationReason: 'Use `hero` with status field instead',
     },
+    search: {
+      type: SearchResultUnion,
+      description: 'Search across all types',
+    },
   },
 });
 
@@ -137,7 +151,13 @@ const StarWarsSchema = new GraphQLSchema({
   description: 'The Star Wars GraphQL API',
   query: QueryType,
   mutation: MutationType,
-  types: [HumanType, CharacterInterface, EpisodeEnum, ReviewInputType],
+  types: [
+    HumanType,
+    CharacterInterface,
+    EpisodeEnum,
+    ReviewInputType,
+    SearchResultUnion,
+  ],
 });
 
 function withDocExplorerStore(Story: React.FC) {
@@ -167,24 +187,51 @@ export const SchemaOverview: Story = {
   },
 };
 
-export const TypeDetail: Story = {
-  name: 'Type detail (Human)',
-  render: function TypeDetailStory() {
-    return <TypeDocumentation type={HumanType} />;
+export const TypeDetailObject: Story = {
+  name: 'Type detail — Object',
+  render: function TypeDetailObjectStory() {
+    return (
+      <>
+        <TypeCard type={HumanType} />
+        <FieldsList type={HumanType} />
+      </>
+    );
   },
 };
 
-export const EnumTypeDetail: Story = {
-  name: 'Type detail (Enum)',
-  render: function EnumTypeDetailStory() {
-    return <TypeDocumentation type={EpisodeEnum} />;
+export const TypeDetailInterface: Story = {
+  name: 'Type detail — Interface',
+  render: function TypeDetailInterfaceStory() {
+    return (
+      <>
+        <TypeCard type={CharacterInterface} />
+        <FieldsList type={CharacterInterface} />
+      </>
+    );
   },
 };
 
-export const InputTypeDetail: Story = {
-  name: 'Type detail (Input)',
-  render: function InputTypeDetailStory() {
-    return <TypeDocumentation type={ReviewInputType} />;
+export const TypeDetailInput: Story = {
+  name: 'Type detail — Input',
+  render: function TypeDetailInputStory() {
+    return (
+      <>
+        <TypeCard type={ReviewInputType} />
+        <FieldsList type={ReviewInputType} />
+      </>
+    );
+  },
+};
+
+export const TypeDetailEnum: Story = {
+  name: 'Type detail — Enum',
+  render: function TypeDetailEnumStory() {
+    return (
+      <>
+        <TypeCard type={EpisodeEnum} />
+        <TypeDocumentation type={EpisodeEnum} hideHeader />
+      </>
+    );
   },
 };
 
@@ -196,6 +243,18 @@ export const FieldDetail: Story = {
   },
 };
 
+export const BreadcrumbNav: Story = {
+  name: 'Breadcrumb navigation',
+  render: function BreadcrumbNavStory() {
+    const navStack: Parameters<typeof Breadcrumb>[0]['navStack'] = [
+      { name: 'Root' },
+      { name: 'Query', def: QueryType },
+      { name: 'Human', def: HumanType },
+    ];
+    return <Breadcrumb navStack={navStack} onNavigateTo={() => {}} />;
+  },
+};
+
 export const TokenColors: Story = {
   name: 'Token colors',
   render: function TokenColorsStory() {
diff --git a/packages/graphiql/cypress/e2e/docs.cy.ts b/packages/graphiql/cypress/e2e/docs.cy.ts
index 031113d68a5..1f0b369c81f 100644
--- a/packages/graphiql/cypress/e2e/docs.cy.ts
+++ b/packages/graphiql/cypress/e2e/docs.cy.ts
@@ -31,12 +31,15 @@ describe('GraphiQL DocExplorer - search', () => {
 
   it('Navigates to a docs entry on selecting a search result', () => {
     cy.dataCy('doc-explorer-option').eq(4).children().click();
-    cy.get('.graphiql-doc-explorer-title').should('have.text', 'TestInput');
+    cy.get('.graphiql-doc-explorer-breadcrumb-current').should(
+      'have.text',
+      'TestInput',
+    );
   });
 
   it('Allows searching fields within a type', () => {
     cy.dataCy('doc-explorer-option').eq(4).children().click();
-    cy.dataCy('doc-explorer-input').type('list');
+    cy.dataCy('doc-explorer-input').clear().type('list');
     cy.dataCy('doc-explorer-option').should('have.length', 14);
     cy.get('.graphiql-doc-explorer-search-divider').should(
       'have.text',
@@ -54,16 +57,21 @@ describe('GraphiQL DocExplorer - search', () => {
 
   it('Navigates back', () => {
     cy.dataCy('doc-explorer-option').eq(4).children().click();
-    cy.get('.graphiql-doc-explorer-back').click();
-    cy.get('.graphiql-doc-explorer-title').should('have.text', 'Docs');
+    // Click the root breadcrumb segment (first link, at depth 0 = "Root")
+    cy.get('.graphiql-doc-explorer-breadcrumb-root').click();
+    // After navigating back, breadcrumb disappears (at root level, no breadcrumb shown)
+    cy.get('.graphiql-doc-explorer-breadcrumb').should('not.exist');
   });
 
   it('Type fields link to their own docs entry', () => {
     cy.dataCy('doc-explorer-option').last().click();
-    cy.get('.graphiql-doc-explorer-title').should('have.text', 'isTest');
-    cy.get('.graphiql-markdown-description').should(
+    cy.get('.graphiql-doc-explorer-breadcrumb-current').should(
       'have.text',
-      'Is this a test schema? Sure it is.\n',
+      'isTest',
+    );
+    cy.get('.graphiql-doc-explorer-field-card-description').should(
+      'have.text',
+      'Is this a test schema? Sure it is.',
     );
   });
 });
@@ -79,20 +87,21 @@ describe('GraphQL DocExplorer - deprecated fields', () => {
     // Show deprecated fields
     cy.contains('Show Deprecated Fields').click();
 
-    // Assert that title is shown
-    cy.get('.graphiql-doc-explorer-section-title').contains(
-      'Deprecated Fields',
-    );
+    // Click into the deprecated field to view its documentation
+    cy.contains(
+      'button.graphiql-doc-explorer-field-row--deprecated',
+      'deprecatedField',
+    ).click();
 
-    // Assert that the deprecated field is shown correctly
-    cy.get('.graphiql-doc-explorer-field-name')
-      .contains('deprecatedField')
-      .closest('.graphiql-doc-explorer-item')
-      .should('contain.text', 'This field is an example of a deprecated field')
-      .and(
-        'contain.html',
-        '<p>No longer in use, try <code>test</code> instead.</p>',
-      );
+    // Assert description and deprecation reason are shown
+    cy.get('.graphiql-doc-explorer-field-card-description').should(
+      'contain.text',
+      'This field is an example of a deprecated field',
+    );
+    cy.get('.graphiql-markdown-deprecation').should(
+      'contain.html',
+      '<p>No longer in use, try <code>test</code> instead.</p>',
+    );
   });
 });
 
@@ -107,13 +116,13 @@ describeOrSkip('GraphQL DocExplorer - deprecated arguments', () => {
     // Open doc explorer
     cy.get('.graphiql-activity-rail-item').eq(0).click();
 
-    // Select query type
-    cy.get('.graphiql-doc-explorer-type-name').first().click();
+    // Use search to navigate directly to hasArgs
+    cy.dataCy('doc-explorer-input').type('hasArgs');
+    cy.dataCy('doc-explorer-option').first().children().first().click();
 
-    cy.get('.graphiql-doc-explorer-field-name').contains('hasArgs').click();
     cy.contains('Show Deprecated Arguments').click();
-    cy.get('.graphiql-doc-explorer-section-title').contains(
-      'Deprecated Arguments',
+    cy.get('.graphiql-doc-explorer-arguments-list-header').contains(
+      'DEPRECATED ARGUMENTS',
     );
     cy.get('.graphiql-markdown-deprecation').should(
       'have.text',

From a3db26e74ffbdc81ae60ddf1c3795437db228ecb Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Wed, 20 May 2026 14:49:02 -0700
Subject: [PATCH 31/38] v6: Restyle @graphiql/plugin-history (#4295)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

- Migrate `@graphiql/plugin-history` CSS to OKLCH tokens.
- New row layout: status dot, mono query name, variables snippet below,
action buttons on the right.
- Replace the bespoke header div with `PanelHeader`; subtitle carries
the ⌥-click hint.
- Storybook stories: `Empty`, `FewRows`, `ManyRows`, `Mixed`, and
individual item variants.

## Test plan

- [x] Open the History panel; confirm the header reads "History" with
the subtitle.
- [x] Run a query; verify the row appears with a green status dot, mono
query name, and a variable snippet if variables were provided.
- [x] Click a history row; confirm the query loads into the editor.
- [ ] ⌥-click a row (diff behavior) and confirm it still works.
- [x] Click "Clear"; confirm rows are removed and the button shows
"Cleared" briefly.
- [x] Open Storybook under "Plugins/History"; verify all stories render
correctly.

Refs: graphql/graphiql#4219
---
 .changeset/restyle-history.md                 |   5 +
 .../src/components.tsx                        | 168 ++++++-----
 .../src/history.stories.tsx                   | 265 ++++++++++++++++++
 .../graphiql-plugin-history/src/style.css     | 133 ++++++---
 packages/graphiql-react/.storybook/main.ts    |   5 +-
 packages/graphiql/cypress/e2e/history.cy.ts   |   8 +-
 6 files changed, 473 insertions(+), 111 deletions(-)
 create mode 100644 .changeset/restyle-history.md
 create mode 100644 packages/graphiql-plugin-history/src/history.stories.tsx

diff --git a/.changeset/restyle-history.md b/.changeset/restyle-history.md
new file mode 100644
index 00000000000..13c41127c8d
--- /dev/null
+++ b/.changeset/restyle-history.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/plugin-history': patch
+---
+
+Restyle to the v6 design. New row layout with status dot, mono name label, and inline variables snippet. Uses `PanelHeader` for the panel chrome.
diff --git a/packages/graphiql-plugin-history/src/components.tsx b/packages/graphiql-plugin-history/src/components.tsx
index 1710eaf6ee7..ba734dbe8d0 100644
--- a/packages/graphiql-plugin-history/src/components.tsx
+++ b/packages/graphiql-plugin-history/src/components.tsx
@@ -12,6 +12,7 @@ import {
   Button,
   Tooltip,
   UnStyledButton,
+  PanelHeader,
 } from '@graphiql/react';
 import { useHistory, useHistoryActions } from './context';
 
@@ -64,24 +65,28 @@ export const History: FC = () => {
   const hasFavorites = Boolean(favorites.length);
   const hasItems = Boolean(items.length);
 
+  const clearButton =
+    clearStatus || hasItems ? (
+      <Button
+        type="button"
+        state={clearStatus || undefined}
+        disabled={!items.length}
+        onClick={handleClearStatus}
+      >
+        {{
+          success: 'Cleared',
+          error: 'Failed to Clear',
+        }[clearStatus!] || 'Clear'}
+      </Button>
+    ) : undefined;
+
   return (
     <section aria-label="History" className="graphiql-history">
-      <div className="graphiql-history-header">
-        History
-        {(clearStatus || hasItems) && (
-          <Button
-            type="button"
-            state={clearStatus || undefined}
-            disabled={!items.length}
-            onClick={handleClearStatus}
-          >
-            {{
-              success: 'Cleared',
-              error: 'Failed to Clear',
-            }[clearStatus!] || 'Clear'}
-          </Button>
-        )}
-      </div>
+      <PanelHeader
+        title="History"
+        subtitle="Last 20 runs."
+        actions={clearButton}
+      />
 
       {hasFavorites && (
         <ul className="graphiql-history-items">
@@ -166,6 +171,10 @@ export const HistoryItem: FC<QueryHistoryItemProps> = props => {
     toggleFavorite(props.item);
   };
 
+  const variablesSnippet = props.item.variables
+    ? formatVariables(props.item.variables)
+    : null;
+
   return (
     <li className={cn('graphiql-history-item', isEditable && 'editable')}>
       {isEditable ? (
@@ -193,54 +202,71 @@ export const HistoryItem: FC<QueryHistoryItemProps> = props => {
         </>
       ) : (
         <>
-          <Tooltip label="Set active">
-            <UnStyledButton
-              type="button"
-              className="graphiql-history-item-label"
-              onClick={handleHistoryItemClick}
-              aria-label="Set active"
-            >
-              {displayName}
-            </UnStyledButton>
-          </Tooltip>
-          <Tooltip label="Edit label">
-            <UnStyledButton
-              type="button"
-              className="graphiql-history-item-action"
-              onClick={handleEditLabel}
-              aria-label="Edit label"
-            >
-              <PenIcon aria-hidden="true" />
-            </UnStyledButton>
-          </Tooltip>
-          <Tooltip
-            label={props.item.favorite ? 'Remove favorite' : 'Add favorite'}
-          >
-            <UnStyledButton
-              type="button"
-              className="graphiql-history-item-action"
-              onClick={handleToggleFavorite}
-              aria-label={
-                props.item.favorite ? 'Remove favorite' : 'Add favorite'
-              }
+          <div className="graphiql-history-item-inner">
+            <div className="graphiql-history-item-row">
+              <span
+                className="graphiql-history-item-status"
+                aria-hidden="true"
+              />
+              <Tooltip label="Set active">
+                <UnStyledButton
+                  type="button"
+                  className="graphiql-history-item-label"
+                  onClick={handleHistoryItemClick}
+                  aria-label="Set active"
+                >
+                  {displayName}
+                </UnStyledButton>
+              </Tooltip>
+            </div>
+            {variablesSnippet && (
+              <div className="graphiql-history-item-meta">
+                <span className="graphiql-history-item-variables">
+                  {variablesSnippet}
+                </span>
+              </div>
+            )}
+          </div>
+          <div className="graphiql-history-item-actions">
+            <Tooltip label="Edit label">
+              <UnStyledButton
+                type="button"
+                className="graphiql-history-item-action"
+                onClick={handleEditLabel}
+                aria-label="Edit label"
+              >
+                <PenIcon aria-hidden="true" />
+              </UnStyledButton>
+            </Tooltip>
+            <Tooltip
+              label={props.item.favorite ? 'Remove favorite' : 'Add favorite'}
             >
-              {props.item.favorite ? (
-                <StarFilledIcon aria-hidden="true" />
-              ) : (
-                <StarIcon aria-hidden="true" />
-              )}
-            </UnStyledButton>
-          </Tooltip>
-          <Tooltip label="Delete from history">
-            <UnStyledButton
-              type="button"
-              className="graphiql-history-item-action"
-              onClick={handleDeleteItemFromHistory}
-              aria-label="Delete from history"
-            >
-              <TrashIcon aria-hidden="true" />
-            </UnStyledButton>
-          </Tooltip>
+              <UnStyledButton
+                type="button"
+                className="graphiql-history-item-action"
+                onClick={handleToggleFavorite}
+                aria-label={
+                  props.item.favorite ? 'Remove favorite' : 'Add favorite'
+                }
+              >
+                {props.item.favorite ? (
+                  <StarFilledIcon aria-hidden="true" />
+                ) : (
+                  <StarIcon aria-hidden="true" />
+                )}
+              </UnStyledButton>
+            </Tooltip>
+            <Tooltip label="Delete from history">
+              <UnStyledButton
+                type="button"
+                className="graphiql-history-item-action"
+                onClick={handleDeleteItemFromHistory}
+                aria-label="Delete from history"
+              >
+                <TrashIcon aria-hidden="true" />
+              </UnStyledButton>
+            </Tooltip>
+          </div>
         </>
       )}
     </li>
@@ -256,3 +282,19 @@ export function formatQuery(query?: string) {
     .replaceAll('}', ' } ')
     .replaceAll(/[\s]{2,}/g, ' ');
 }
+
+export function formatVariables(variables: string) {
+  try {
+    const parsed = JSON.parse(variables) as Record<string, unknown>;
+    const entries = Object.entries(parsed);
+    if (!entries.length) {
+      return null;
+    }
+    return entries
+      .slice(0, 3)
+      .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+      .join(', ');
+  } catch {
+    return variables.slice(0, 60);
+  }
+}
diff --git a/packages/graphiql-plugin-history/src/history.stories.tsx b/packages/graphiql-plugin-history/src/history.stories.tsx
new file mode 100644
index 00000000000..2efee2e1bf5
--- /dev/null
+++ b/packages/graphiql-plugin-history/src/history.stories.tsx
@@ -0,0 +1,265 @@
+import type { ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  GraphiQLProvider,
+  Tooltip,
+  PanelHeader,
+  Button,
+} from '@graphiql/react';
+import { History, HistoryItem } from './components';
+import { HistoryStore } from './context';
+import './style.css';
+
+// ---------------------------------------------------------------------------
+// Shared decorator: History items need GraphiQLProvider + HistoryStore
+// ---------------------------------------------------------------------------
+
+function withHistoryContext(children: ReactNode) {
+  return (
+    <Tooltip.Provider>
+      <GraphiQLProvider fetcher={() => Promise.resolve({ data: {} })}>
+        <HistoryStore>
+          <div style={{ width: 320, background: 'oklch(var(--bg-elevated))' }}>
+            {children}
+          </div>
+        </HistoryStore>
+      </GraphiQLProvider>
+    </Tooltip.Provider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: 'Plugins/History',
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+// ---------------------------------------------------------------------------
+// PanelHeader (no context required)
+// ---------------------------------------------------------------------------
+
+export const Header: Story = {
+  render: () => (
+    <div style={{ width: 320, background: 'oklch(var(--bg-elevated))' }}>
+      <PanelHeader
+        title="History"
+        subtitle="Last 20 runs."
+        actions={
+          <Button type="button" disabled>
+            Clear
+          </Button>
+        }
+      />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Single item — query only
+// ---------------------------------------------------------------------------
+
+export const ItemQueryOnly: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        <HistoryItem
+          item={{
+            query: 'query GetUser { user { id name email } }',
+            favorite: false,
+          }}
+        />
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Single item — with variables snippet
+// ---------------------------------------------------------------------------
+
+export const ItemWithVariables: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        <HistoryItem
+          item={{
+            query: 'query GetUser($id: ID!) { user(id: $id) { id name } }',
+            variables: JSON.stringify({ id: '123', role: 'admin' }),
+            operationName: 'GetUser',
+            favorite: false,
+          }}
+        />
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Favorite item
+// ---------------------------------------------------------------------------
+
+export const ItemFavorite: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        <HistoryItem
+          item={{
+            query: 'query Me { viewer { login avatarUrl } }',
+            operationName: 'Me',
+            favorite: true,
+          }}
+        />
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Custom label
+// ---------------------------------------------------------------------------
+
+export const ItemWithLabel: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        <HistoryItem
+          item={{
+            query: 'query { repositories { totalCount } }',
+            label: 'Repo count check',
+            favorite: false,
+          }}
+        />
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Empty state (full History component)
+// ---------------------------------------------------------------------------
+
+export const Empty: Story = {
+  render: () => withHistoryContext(<History />),
+};
+
+// ---------------------------------------------------------------------------
+// Few rows
+// ---------------------------------------------------------------------------
+
+export const FewRows: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        <HistoryItem
+          item={{
+            query: 'query Me { viewer { login } }',
+            operationName: 'Me',
+            favorite: false,
+          }}
+        />
+        <HistoryItem
+          item={{
+            query: 'query GetUser($id: ID!) { user(id: $id) { id name } }',
+            variables: JSON.stringify({ id: '42' }),
+            operationName: 'GetUser',
+            favorite: false,
+          }}
+        />
+        <HistoryItem
+          item={{
+            query:
+              'mutation CreatePost($input: PostInput!) { createPost(input: $input) { id } }',
+            variables: JSON.stringify({
+              input: { title: 'Hello', body: 'World' },
+            }),
+            operationName: 'CreatePost',
+            favorite: false,
+          }}
+        />
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Many rows
+// ---------------------------------------------------------------------------
+
+const manyItems = Array.from({ length: 10 }, (_, i) => ({
+  query: `query Query${i + 1} { node(id: "${i + 1}") { id ... on User { name } } }`,
+  operationName: `Query${i + 1}`,
+  favorite: false,
+}));
+
+export const ManyRows: Story = {
+  render: () =>
+    withHistoryContext(
+      <ul className="graphiql-history-items" style={{ padding: 0, margin: 0 }}>
+        {manyItems.map(item => (
+          <HistoryItem key={item.operationName} item={item} />
+        ))}
+      </ul>,
+    ),
+};
+
+// ---------------------------------------------------------------------------
+// Mixed: favorites + regular + with variables
+// ---------------------------------------------------------------------------
+
+export const Mixed: Story = {
+  render: () =>
+    withHistoryContext(
+      <>
+        <ul
+          className="graphiql-history-items"
+          style={{ padding: 0, margin: 0 }}
+        >
+          <HistoryItem
+            item={{
+              query: 'query Me { viewer { login avatarUrl } }',
+              operationName: 'Me',
+              favorite: true,
+              label: 'My profile',
+            }}
+          />
+          <HistoryItem
+            item={{
+              query: 'subscription OnComment { commentAdded { id body } }',
+              operationName: 'OnComment',
+              favorite: true,
+            }}
+          />
+        </ul>
+        <div className="graphiql-history-item-spacer" />
+        <ul
+          className="graphiql-history-items"
+          style={{ padding: 0, margin: 0 }}
+        >
+          <HistoryItem
+            item={{
+              query:
+                'query GetUser($id: ID!) { user(id: $id) { id name email } }',
+              variables: JSON.stringify({ id: '123', role: 'admin' }),
+              operationName: 'GetUser',
+              favorite: false,
+            }}
+          />
+          <HistoryItem
+            item={{
+              query: 'mutation DeleteUser($id: ID!) { deleteUser(id: $id) }',
+              operationName: 'DeleteUser',
+              favorite: false,
+            }}
+          />
+          <HistoryItem
+            item={{
+              query: '{ __typename }',
+              favorite: false,
+            }}
+          />
+        </ul>
+      </>,
+    ),
+};
diff --git a/packages/graphiql-plugin-history/src/style.css b/packages/graphiql-plugin-history/src/style.css
index ac536135f29..7d6e977623c 100644
--- a/packages/graphiql-plugin-history/src/style.css
+++ b/packages/graphiql-plugin-history/src/style.css
@@ -1,44 +1,29 @@
-.graphiql-history-header {
-  font-size: var(--font-size-h2);
-  font-weight: var(--font-weight-medium);
+.graphiql-history {
   display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-.graphiql-history-header button {
-  font-size: var(--font-size-inline-code);
-  padding: var(--px-6) var(--px-10);
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
 }
 
 .graphiql-history-items {
-  margin: var(--px-16) 0 0;
+  margin: 0;
   list-style: none;
   padding: 0;
+  overflow-y: auto;
+  flex: 1;
 }
 
 .graphiql-history-item {
-  border-radius: var(--border-radius-4);
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  border-bottom: 1px solid oklch(var(--border-default));
   display: flex;
-  font-size: var(--font-size-inline-code);
-  font-family: var(--font-family-mono);
-  height: 34px;
+  align-items: stretch;
 
   &:hover {
-    color: hsl(var(--color-neutral));
-    background-color: hsla(var(--color-neutral), var(--alpha-background-light));
-  }
-
-  &:not(:first-child) {
-    margin-top: var(--px-4);
+    background-color: oklch(var(--accent-blue) / 0.06);
   }
 
   &.editable {
-    background-color: hsla(
-      var(--color-primary),
-      var(--alpha-background-medium)
-    );
+    background-color: oklch(var(--accent-blue) / 0.08);
 
     & > input {
       background: transparent;
@@ -46,27 +31,27 @@
       flex: 1;
       margin: 0;
       outline: none;
-      padding: 0 var(--px-10);
+      padding: 0 var(--px-14);
       width: 100%;
+      color: oklch(var(--fg-default));
+      font-family: var(--font-family-mono);
+      font-size: var(--font-size-mono);
 
       &::placeholder {
-        color: hsla(var(--color-neutral), var(--alpha-secondary));
+        color: oklch(var(--fg-disabled));
       }
     }
 
     & > button {
-      color: hsl(var(--color-primary));
+      color: oklch(var(--accent-blue));
       padding: 0 var(--px-10);
 
       &:active {
-        background-color: hsla(
-          var(--color-primary),
-          var(--alpha-background-heavy)
-        );
+        background-color: oklch(var(--accent-blue) / 0.12);
       }
 
       &:focus {
-        outline: hsl(var(--color-primary)) auto 1px;
+        outline: oklch(var(--accent-blue)) auto 1px;
       }
 
       & > svg {
@@ -76,30 +61,92 @@
   }
 }
 
-button.graphiql-history-item-label {
+.graphiql-history-item-inner {
+  padding: var(--px-8) var(--px-14);
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
   flex: 1;
-  padding: var(--px-8) var(--px-10);
+}
+
+.graphiql-history-item-row {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  min-width: 0;
+}
+
+.graphiql-history-item-status {
+  flex-shrink: 0;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background-color: oklch(var(--accent-green));
+}
+
+.graphiql-history-item-status.error {
+  background-color: oklch(var(--accent-red));
+}
+
+.graphiql-history-item-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: oklch(var(--fg-default));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-mono);
+  text-align: left;
+}
+
+.graphiql-history-item-meta {
+  display: flex;
+  align-items: center;
+  gap: var(--px-6);
+  min-width: 0;
+  padding-left: 12px;
+}
+
+.graphiql-history-item-variables {
+  flex: 1;
+  min-width: 0;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-eyebrow);
+}
+
+.graphiql-history-item-actions {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  padding-right: var(--px-6);
 }
 
-button.graphiql-history-item-action {
+.graphiql-history-item-action {
   align-items: center;
-  color: hsla(var(--color-neutral), var(--alpha-secondary));
+  color: oklch(var(--fg-disabled));
   display: flex;
-  padding: var(--px-8) var(--px-6);
+  padding: var(--px-6);
+  border-radius: var(--radius-sm);
 
   &:hover {
-    color: hsl(var(--color-neutral));
+    color: oklch(var(--fg-default));
+    background-color: oklch(var(--fg-default) / 0.06);
   }
 
   & > svg {
-    height: 14px;
-    width: 14px;
+    height: 12px;
+    width: 12px;
   }
 }
 
 .graphiql-history-item-spacer {
-  height: var(--px-16);
+  height: 1px;
+  background-color: oklch(var(--border-strong));
+  margin: var(--px-8) 0;
 }
diff --git a/packages/graphiql-react/.storybook/main.ts b/packages/graphiql-react/.storybook/main.ts
index dddd2d457b7..cbe952ed5bf 100644
--- a/packages/graphiql-react/.storybook/main.ts
+++ b/packages/graphiql-react/.storybook/main.ts
@@ -1,7 +1,10 @@
 import type { StorybookConfig } from '@storybook/react-vite';
 
 const config: StorybookConfig = {
-  stories: ['../src/**/*.stories.@(ts|tsx)'],
+  stories: [
+    '../src/**/*.stories.@(ts|tsx)',
+    '../../graphiql-plugin-history/src/**/*.stories.@(ts|tsx)',
+  ],
   addons: ['@storybook/addon-a11y', '@storybook/addon-vitest'],
   framework: { name: '@storybook/react-vite', options: {} },
 };
diff --git a/packages/graphiql/cypress/e2e/history.cy.ts b/packages/graphiql/cypress/e2e/history.cy.ts
index e38a5b2598a..da9b7d48675 100644
--- a/packages/graphiql/cypress/e2e/history.cy.ts
+++ b/packages/graphiql/cypress/e2e/history.cy.ts
@@ -82,7 +82,7 @@ describe('history', () => {
     cy.get('ul.graphiql-history-items li').should('have.length', 2);
 
     cy.get(
-      '.graphiql-history-item:nth-child(2) > button[aria-label="Delete from history"]',
+      '.graphiql-history-item:nth-child(2) button[aria-label="Delete from history"]',
     ).click();
     cy.get('.graphiql-history-item').should('have.length', 1);
   });
@@ -95,7 +95,7 @@ describe('history', () => {
     cy.get('button[aria-label="Show History"]').click();
     cy.get('ul.graphiql-history-items li').should('have.length', 2);
 
-    cy.get('.graphiql-history-header > button:last-child').click();
+    cy.get('.graphiql-panel-header-actions button:last-child').click();
     cy.get('.graphiql-history-item').should('have.length', 0);
   });
 
@@ -113,7 +113,7 @@ describe('history', () => {
     const items = '.graphiql-history ul:last-of-type .graphiql-history-item';
 
     cy.get(
-      '.graphiql-history-item:nth-child(2) > button[aria-label="Add favorite"]',
+      '.graphiql-history-item:nth-child(2) button[aria-label="Add favorite"]',
     ).click();
     cy.get('.graphiql-history ul').should('have.length', 2); // favorites and items
     cy.get(favorites).should('have.length', 1);
@@ -121,7 +121,7 @@ describe('history', () => {
     cy.get('.graphiql-history-item-label').eq(0).should('have.text', 'Test'); // favorite so now at top of a list
 
     cy.get(
-      '.graphiql-history-item:nth-child(1) > button[aria-label="Remove favorite"]',
+      '.graphiql-history-item:nth-child(1) button[aria-label="Remove favorite"]',
     ).click();
     cy.get('.graphiql-history ul').should('have.length', 1); // just items
     cy.get(items).should('have.length', 2);

From eb46e2fe17413d9f9a52c7d7780b5cbaf799050e Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Wed, 20 May 2026 15:55:32 -0700
Subject: [PATCH 32/38] v6: Show operation pill on History rows (#4316)

## Summary

- Show a `MethodPill` (`QRY`/`MUT`/`SUB`) per History row in place of
the green status dot.
- `QueryStoreItem` gains an optional `operation` field, populated at
write time from the parsed query.
- The Clear button drops the green-on-success state; rows disappearing
is the feedback.

## Test plan

- Open the History panel, run a query/mutation/subscription, and confirm
each row shows the right pill.
- Click "Clear"; rows are removed without any color flash on the button.
- Open Storybook under "Plugins/History"; check the updated `Mixed`
story.

Refs: graphql/graphiql#4219
---
 .changeset/history-method-pill.md             |  6 ++
 .../src/components.tsx                        | 59 ++++-------------
 .../src/history.stories.tsx                   | 13 ++++
 .../graphiql-plugin-history/src/style.css     | 12 ----
 .../src/components/method-pill/index.tsx      |  3 +-
 .../graphiql-toolkit/src/storage/history.ts   | 66 ++++++++++---------
 .../graphiql-toolkit/src/storage/query.ts     |  4 ++
 7 files changed, 73 insertions(+), 90 deletions(-)
 create mode 100644 .changeset/history-method-pill.md

diff --git a/.changeset/history-method-pill.md b/.changeset/history-method-pill.md
new file mode 100644
index 00000000000..29cc9dfa7fa
--- /dev/null
+++ b/.changeset/history-method-pill.md
@@ -0,0 +1,6 @@
+---
+'@graphiql/plugin-history': patch
+'@graphiql/toolkit': patch
+---
+
+Show a `MethodPill` (`QRY`/`MUT`/`SUB`) on each History row in place of the green status dot. `QueryStoreItem` gains an optional `operation` field, populated at write time from the parsed query. The Clear button no longer flashes green on success.
diff --git a/packages/graphiql-plugin-history/src/components.tsx b/packages/graphiql-plugin-history/src/components.tsx
index ba734dbe8d0..1d594430f01 100644
--- a/packages/graphiql-plugin-history/src/components.tsx
+++ b/packages/graphiql-plugin-history/src/components.tsx
@@ -10,23 +10,13 @@ import {
   useGraphiQL,
   pick,
   Button,
+  MethodPill,
   Tooltip,
   UnStyledButton,
   PanelHeader,
 } from '@graphiql/react';
 import { useHistory, useHistoryActions } from './context';
 
-// Fix error from react-compiler
-// Support value blocks (conditional, logical, optional chaining, etc.) within a try/catch statement
-function handleDelete(
-  items: QueryStoreItem[],
-  deleteFromHistory: ReturnType<typeof useHistoryActions>['deleteFromHistory'],
-) {
-  for (const item of items) {
-    deleteFromHistory(item, true);
-  }
-}
-
 export const History: FC = () => {
   const all = useHistory();
   const { deleteFromHistory } = useHistoryActions();
@@ -42,43 +32,19 @@ export const History: FC = () => {
     items = items.filter(item => !item.favorite);
   }
 
-  const [clearStatus, setClearStatus] = useState<'success' | 'error' | null>(
-    null,
-  );
-  useEffect(() => {
-    if (clearStatus) {
-      // reset the button after a couple seconds
-      setTimeout(() => {
-        setClearStatus(null);
-      }, 2000);
-    }
-  }, [clearStatus]);
-
-  const handleClearStatus = () => {
-    try {
-      handleDelete(items, deleteFromHistory);
-      setClearStatus('success');
-    } catch {
-      setClearStatus('error');
+  const handleClear = () => {
+    for (const item of items) {
+      deleteFromHistory(item, true);
     }
   };
   const hasFavorites = Boolean(favorites.length);
   const hasItems = Boolean(items.length);
 
-  const clearButton =
-    clearStatus || hasItems ? (
-      <Button
-        type="button"
-        state={clearStatus || undefined}
-        disabled={!items.length}
-        onClick={handleClearStatus}
-      >
-        {{
-          success: 'Cleared',
-          error: 'Failed to Clear',
-        }[clearStatus!] || 'Clear'}
-      </Button>
-    ) : undefined;
+  const clearButton = hasItems ? (
+    <Button type="button" onClick={handleClear}>
+      Clear
+    </Button>
+  ) : undefined;
 
   return (
     <section aria-label="History" className="graphiql-history">
@@ -204,10 +170,9 @@ export const HistoryItem: FC<QueryHistoryItemProps> = props => {
         <>
           <div className="graphiql-history-item-inner">
             <div className="graphiql-history-item-row">
-              <span
-                className="graphiql-history-item-status"
-                aria-hidden="true"
-              />
+              {props.item.operation && (
+                <MethodPill operation={props.item.operation} aria-hidden />
+              )}
               <Tooltip label="Set active">
                 <UnStyledButton
                   type="button"
diff --git a/packages/graphiql-plugin-history/src/history.stories.tsx b/packages/graphiql-plugin-history/src/history.stories.tsx
index 2efee2e1bf5..16c8f1c7a4d 100644
--- a/packages/graphiql-plugin-history/src/history.stories.tsx
+++ b/packages/graphiql-plugin-history/src/history.stories.tsx
@@ -72,6 +72,7 @@ export const ItemQueryOnly: Story = {
         <HistoryItem
           item={{
             query: 'query GetUser { user { id name email } }',
+            operation: 'query',
             favorite: false,
           }}
         />
@@ -92,6 +93,7 @@ export const ItemWithVariables: Story = {
             query: 'query GetUser($id: ID!) { user(id: $id) { id name } }',
             variables: JSON.stringify({ id: '123', role: 'admin' }),
             operationName: 'GetUser',
+            operation: 'query',
             favorite: false,
           }}
         />
@@ -111,6 +113,7 @@ export const ItemFavorite: Story = {
           item={{
             query: 'query Me { viewer { login avatarUrl } }',
             operationName: 'Me',
+            operation: 'query',
             favorite: true,
           }}
         />
@@ -129,6 +132,7 @@ export const ItemWithLabel: Story = {
         <HistoryItem
           item={{
             query: 'query { repositories { totalCount } }',
+            operation: 'query',
             label: 'Repo count check',
             favorite: false,
           }}
@@ -157,6 +161,7 @@ export const FewRows: Story = {
           item={{
             query: 'query Me { viewer { login } }',
             operationName: 'Me',
+            operation: 'query',
             favorite: false,
           }}
         />
@@ -165,6 +170,7 @@ export const FewRows: Story = {
             query: 'query GetUser($id: ID!) { user(id: $id) { id name } }',
             variables: JSON.stringify({ id: '42' }),
             operationName: 'GetUser',
+            operation: 'query',
             favorite: false,
           }}
         />
@@ -176,6 +182,7 @@ export const FewRows: Story = {
               input: { title: 'Hello', body: 'World' },
             }),
             operationName: 'CreatePost',
+            operation: 'mutation',
             favorite: false,
           }}
         />
@@ -190,6 +197,7 @@ export const FewRows: Story = {
 const manyItems = Array.from({ length: 10 }, (_, i) => ({
   query: `query Query${i + 1} { node(id: "${i + 1}") { id ... on User { name } } }`,
   operationName: `Query${i + 1}`,
+  operation: 'query' as const,
   favorite: false,
 }));
 
@@ -220,6 +228,7 @@ export const Mixed: Story = {
             item={{
               query: 'query Me { viewer { login avatarUrl } }',
               operationName: 'Me',
+              operation: 'query',
               favorite: true,
               label: 'My profile',
             }}
@@ -228,6 +237,7 @@ export const Mixed: Story = {
             item={{
               query: 'subscription OnComment { commentAdded { id body } }',
               operationName: 'OnComment',
+              operation: 'subscription',
               favorite: true,
             }}
           />
@@ -243,6 +253,7 @@ export const Mixed: Story = {
                 'query GetUser($id: ID!) { user(id: $id) { id name email } }',
               variables: JSON.stringify({ id: '123', role: 'admin' }),
               operationName: 'GetUser',
+              operation: 'query',
               favorite: false,
             }}
           />
@@ -250,12 +261,14 @@ export const Mixed: Story = {
             item={{
               query: 'mutation DeleteUser($id: ID!) { deleteUser(id: $id) }',
               operationName: 'DeleteUser',
+              operation: 'mutation',
               favorite: false,
             }}
           />
           <HistoryItem
             item={{
               query: '{ __typename }',
+              operation: 'query',
               favorite: false,
             }}
           />
diff --git a/packages/graphiql-plugin-history/src/style.css b/packages/graphiql-plugin-history/src/style.css
index 7d6e977623c..dea382f17e3 100644
--- a/packages/graphiql-plugin-history/src/style.css
+++ b/packages/graphiql-plugin-history/src/style.css
@@ -77,18 +77,6 @@
   min-width: 0;
 }
 
-.graphiql-history-item-status {
-  flex-shrink: 0;
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  background-color: oklch(var(--accent-green));
-}
-
-.graphiql-history-item-status.error {
-  background-color: oklch(var(--accent-red));
-}
-
 .graphiql-history-item-label {
   flex: 1;
   min-width: 0;
diff --git a/packages/graphiql-react/src/components/method-pill/index.tsx b/packages/graphiql-react/src/components/method-pill/index.tsx
index 49ef2ad7ae5..bf888e407b9 100644
--- a/packages/graphiql-react/src/components/method-pill/index.tsx
+++ b/packages/graphiql-react/src/components/method-pill/index.tsx
@@ -1,7 +1,8 @@
 import type { FC } from 'react';
+import type { Operation } from '@graphiql/toolkit';
 import './index.css';
 
-export type Operation = 'query' | 'mutation' | 'subscription';
+export type { Operation };
 
 const LABELS: Record<Operation, string> = {
   query: 'QRY',
diff --git a/packages/graphiql-toolkit/src/storage/history.ts b/packages/graphiql-toolkit/src/storage/history.ts
index 3f301b5e4ef..def21a1cb2b 100644
--- a/packages/graphiql-toolkit/src/storage/history.ts
+++ b/packages/graphiql-toolkit/src/storage/history.ts
@@ -1,4 +1,8 @@
-import { parse } from 'graphql';
+import {
+  parse,
+  type DocumentNode,
+  type OperationDefinitionNode,
+} from 'graphql';
 
 import { StorageAPI } from './base';
 import { QueryStore, QueryStoreItem } from './query';
@@ -25,28 +29,23 @@ export class HistoryStore {
     this.queries = [...this.history.fetchAll(), ...this.favorite.fetchAll()];
   }
 
-  private shouldSaveQuery(
-    query?: string,
-    variables?: string,
-    headers?: string,
-    lastQuerySaved?: QueryStoreItem,
-  ) {
-    if (!query) {
-      return false;
+  private parseForHistory(
+    query: string | undefined,
+    variables: string | undefined,
+    headers: string | undefined,
+    lastQuerySaved: QueryStoreItem | undefined,
+  ): DocumentNode | null {
+    if (!query || query.length > MAX_QUERY_SIZE) {
+      return null;
     }
-
+    let document: DocumentNode;
     try {
-      parse(query);
+      document = parse(query);
     } catch {
-      return false;
-    }
-
-    // Don't try to save giant queries
-    if (query.length > MAX_QUERY_SIZE) {
-      return false;
+      return null;
     }
     if (!lastQuerySaved) {
-      return true;
+      return document;
     }
     if (JSON.stringify(query) === JSON.stringify(lastQuerySaved.query)) {
       if (
@@ -55,17 +54,17 @@ export class HistoryStore {
         if (
           JSON.stringify(headers) === JSON.stringify(lastQuerySaved.headers)
         ) {
-          return false;
+          return null;
         }
         if (headers && !lastQuerySaved.headers) {
-          return false;
+          return null;
         }
       }
       if (variables && !lastQuerySaved.variables) {
-        return false;
+        return null;
       }
     }
-    return true;
+    return document;
   }
 
   updateHistory = ({
@@ -74,21 +73,24 @@ export class HistoryStore {
     headers,
     operationName,
   }: QueryStoreItem) => {
-    if (
-      !this.shouldSaveQuery(
-        query,
-        variables,
-        headers,
-        this.history.fetchRecent(),
-      )
-    ) {
+    const document = this.parseForHistory(
+      query,
+      variables,
+      headers,
+      this.history.fetchRecent(),
+    );
+    if (!document) {
       return;
     }
+    const operation = document.definitions.find(
+      (d): d is OperationDefinitionNode => d.kind === 'OperationDefinition',
+    )?.operation;
     this.history.push({
       query,
       variables,
       headers,
       operationName,
+      operation,
     });
     const historyQueries = this.history.items;
     const favoriteQueries = this.favorite.items;
@@ -100,6 +102,7 @@ export class HistoryStore {
     variables,
     headers,
     operationName,
+    operation,
     label,
     favorite,
   }: QueryStoreItem) {
@@ -108,6 +111,7 @@ export class HistoryStore {
       variables,
       headers,
       operationName,
+      operation,
       label,
     };
     if (favorite) {
@@ -128,6 +132,7 @@ export class HistoryStore {
       variables,
       headers,
       operationName,
+      operation,
       label,
       favorite,
     }: QueryStoreItem,
@@ -138,6 +143,7 @@ export class HistoryStore {
       variables,
       headers,
       operationName,
+      operation,
       label,
     };
     if (favorite) {
diff --git a/packages/graphiql-toolkit/src/storage/query.ts b/packages/graphiql-toolkit/src/storage/query.ts
index 9fea0e93b4a..59abf52a6ac 100644
--- a/packages/graphiql-toolkit/src/storage/query.ts
+++ b/packages/graphiql-toolkit/src/storage/query.ts
@@ -1,10 +1,14 @@
+import type { OperationTypeNode } from 'graphql';
 import { StorageAPI } from './base';
 
+export type Operation = `${OperationTypeNode}`;
+
 export type QueryStoreItem = {
   query?: string;
   variables?: string;
   headers?: string;
   operationName?: string;
+  operation?: Operation;
   label?: string;
   favorite?: boolean;
 };

From 03535abc736d4479ac558320c477ff3b2e05b3f5 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Wed, 27 May 2026 11:10:55 -0700
Subject: [PATCH 33/38] v6: Add response pane header with view toggle (#4321)

## Summary

A new header sits above the response pane, showing the status code,
elapsed time, response size, a JSON / Tree / Table view toggle, and a
copy button. Status / time / size come from a new `lastResponse` field
on the execution slice, populated when the fetcher resolves. The view
toggle is wired through the storage slice, so reloading the app brings
you back to whichever view you last picked. Tree and Table render
placeholders for now; their implementations land in follow-up PRs.

## Test plan

- [x] On the deploy preview, run a query and confirm the header
populates with `200 OK`, an `Nms` value, and a byte count.
- [x] Click each segmented option (JSON / Tree / Table); JSON renders
the response, Tree and Table render their placeholder; reload and
confirm the last-picked view comes back.
- [x] Hover the copy button and confirm the tooltip; click it and
confirm the clipboard receives the formatted response.
- [x] Open Storybook `Components/ResponseHeader` on the deploy preview
and walk the variants.

Refs: graphql/graphiql#4219
---
 .changeset/response-pane-header.md            |   5 +
 .../graphiql-react/src/components/index.ts    |   2 +
 .../src/components/provider.tsx               |  13 ++
 .../src/components/response-editor.tsx        |  74 ++++++++---
 .../src/components/response-header/index.css  |  82 ++++++++++++
 .../src/components/response-header/index.tsx  |  83 ++++++++++++
 .../response-header.stories.tsx               |  75 +++++++++++
 .../response-header/response-header.test.tsx  | 122 ++++++++++++++++++
 packages/graphiql-react/src/constants.ts      |   1 +
 packages/graphiql-react/src/index.ts          |   1 +
 .../src/stores/execution.spec.ts              |  89 +++++++++++++
 .../graphiql-react/src/stores/execution.ts    | 104 +++++++++++++--
 packages/graphiql-react/src/stores/index.ts   |   3 +
 13 files changed, 629 insertions(+), 25 deletions(-)
 create mode 100644 .changeset/response-pane-header.md
 create mode 100644 packages/graphiql-react/src/components/response-header/index.css
 create mode 100644 packages/graphiql-react/src/components/response-header/index.tsx
 create mode 100644 packages/graphiql-react/src/components/response-header/response-header.stories.tsx
 create mode 100644 packages/graphiql-react/src/components/response-header/response-header.test.tsx
 create mode 100644 packages/graphiql-react/src/stores/execution.spec.ts

diff --git a/.changeset/response-pane-header.md b/.changeset/response-pane-header.md
new file mode 100644
index 00000000000..d40b01c3cda
--- /dev/null
+++ b/.changeset/response-pane-header.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a response pane header showing status, elapsed time, response size, a JSON / Tree / Table view toggle, and a copy button. The selected view is persisted in storage and restored on reload. Tree and Table views render a placeholder until their implementations land.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index ad40498772f..a229d3cb622 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -37,3 +37,5 @@ export { SidePanel, SidePanelView } from './side-panel';
 export type { SidePanelViewProps } from './side-panel';
 export { ActivityRail } from './activity-rail';
 export type { ActivityRailProps } from './activity-rail';
+export { ResponseHeader } from './response-header';
+export type { ResponseHeaderProps } from './response-header';
diff --git a/packages/graphiql-react/src/components/provider.tsx b/packages/graphiql-react/src/components/provider.tsx
index 727cbd18e94..33b1262f9f8 100644
--- a/packages/graphiql-react/src/components/provider.tsx
+++ b/packages/graphiql-react/src/components/provider.tsx
@@ -18,6 +18,7 @@ import {
   createSchemaSlice,
   createThemeSlice,
   createStorageSlice,
+  isResponseView,
   ExecutionProps,
   PluginProps,
   SchemaProps,
@@ -211,6 +212,17 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
       }
     }
 
+    function getInitialResponseView() {
+      const stored = storage.get(STORAGE_KEY.responseView);
+      if (isResponseView(stored)) {
+        return stored;
+      }
+      if (typeof stored === 'string') {
+        storage.set(STORAGE_KEY.responseView, '');
+      }
+      return 'json';
+    }
+
     function getInitialState() {
       // We only need to compute it lazily during the initial render.
       const query = props.initialQuery ?? storage.get(STORAGE_KEY.query);
@@ -296,6 +308,7 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
       actions.setPlugins(plugins);
       actions.setVisiblePlugin(getInitialVisiblePlugin());
       actions.setTheme(getInitialTheme());
+      actions.setResponseView(getInitialResponseView());
 
       return store;
     }
diff --git a/packages/graphiql-react/src/components/response-editor.tsx b/packages/graphiql-react/src/components/response-editor.tsx
index 3ef1232c170..0cc01727c56 100644
--- a/packages/graphiql-react/src/components/response-editor.tsx
+++ b/packages/graphiql-react/src/components/response-editor.tsx
@@ -3,6 +3,7 @@ import { ComponentType, FC, useEffect, useRef } from 'react';
 import { createRoot, Root } from 'react-dom/client';
 import { useGraphiQL, useGraphiQLActions } from './provider';
 import { ImagePreview } from './image-preview';
+import { ResponseHeader } from './response-header';
 import {
   getOrCreateModel,
   createEditor,
@@ -14,6 +15,7 @@ import { KEY_BINDINGS, URI_NAME } from '../constants';
 import type { EditorProps } from '../types';
 import type * as monaco from 'monaco-editor';
 import { useMonaco } from '../stores';
+import type { ResponseView } from '../stores';
 
 type ResponseTooltipType = ComponentType<{
   /**
@@ -37,12 +39,36 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
   responseTooltip: ResponseTooltip,
   ...props
 }) => {
-  const { setEditor, run } = useGraphiQLActions();
-  const { fetchError, validationErrors, responseEditor, uriInstanceId } =
-    useGraphiQL(
-      pick('fetchError', 'validationErrors', 'responseEditor', 'uriInstanceId'),
-    );
+  const { setEditor, run, setResponseView } = useGraphiQLActions();
+  const {
+    fetchError,
+    validationErrors,
+    responseEditor,
+    uriInstanceId,
+    lastResponse,
+    responseView,
+  } = useGraphiQL(
+    pick(
+      'fetchError',
+      'validationErrors',
+      'responseEditor',
+      'uriInstanceId',
+      'lastResponse',
+      'responseView',
+    ),
+  );
   const ref = useRef<HTMLDivElement>(null!);
+
+  async function handleCopy() {
+    const value = responseEditor?.getValue();
+    if (value) {
+      await navigator.clipboard.writeText(value);
+    }
+  }
+
+  function handleViewChange(view: ResponseView) {
+    setResponseView(view);
+  }
   const monaco = useMonaco(state => state.monaco);
   useEffect(() => {
     if (fetchError) {
@@ -141,15 +167,33 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
   }, [monaco]); // eslint-disable-line react-hooks/exhaustive-deps -- only on mount
 
   return (
-    <section
-      ref={ref}
-      aria-label="Result Window"
-      aria-live="polite"
-      aria-atomic="true"
-      tabIndex={0}
-      onKeyDown={onEditorContainerKeyDown}
-      {...props}
-      className={cn('result-window', props.className)}
-    />
+    <div {...props} className={cn('graphiql-response-pane', props.className)}>
+      <ResponseHeader
+        status={lastResponse?.status}
+        timeMs={lastResponse?.timeMs}
+        sizeBytes={lastResponse?.sizeBytes}
+        view={responseView}
+        onViewChange={handleViewChange}
+        onCopy={handleCopy}
+      />
+      {responseView === 'json' ? (
+        <section
+          ref={ref}
+          aria-label="Result Window"
+          aria-live="polite"
+          aria-atomic="true"
+          tabIndex={0}
+          onKeyDown={onEditorContainerKeyDown}
+          className="result-window"
+        />
+      ) : (
+        <div className="graphiql-response-empty-state" role="status">
+          <span>
+            {responseView === 'tree' ? 'Tree' : 'Table'} view is not yet
+            available.
+          </span>
+        </div>
+      )}
+    </div>
   );
 };
diff --git a/packages/graphiql-react/src/components/response-header/index.css b/packages/graphiql-react/src/components/response-header/index.css
new file mode 100644
index 00000000000..ddcc940f343
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-header/index.css
@@ -0,0 +1,82 @@
+.graphiql-response-header {
+  display: flex;
+  align-items: center;
+  gap: var(--px-8);
+  height: 32px;
+  padding: 0 var(--px-14);
+  border-bottom: 1px solid oklch(var(--border-default));
+  background: oklch(var(--bg-elevated));
+  flex-shrink: 0;
+}
+
+.graphiql-response-status {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  font-family: var(--font-family-mono);
+  font-size: 11.5px;
+  line-height: 1;
+}
+
+.graphiql-response-status-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.graphiql-response-status--ok .graphiql-response-status-dot {
+  background: oklch(var(--accent-green));
+}
+
+.graphiql-response-status--error .graphiql-response-status-dot {
+  background: oklch(var(--accent-red));
+}
+
+.graphiql-response-status--ok .graphiql-response-status-code {
+  color: oklch(var(--accent-green));
+}
+
+.graphiql-response-status--error .graphiql-response-status-code {
+  color: oklch(var(--accent-red));
+}
+
+.graphiql-response-meta {
+  font-family: var(--font-family-mono);
+  font-size: 11.5px;
+  color: oklch(var(--fg-muted));
+  line-height: 1;
+}
+
+.graphiql-response-header-spacer {
+  flex: 1;
+}
+
+/* ToolbarButton defaults to --toolbar-width (40px); shrink it so the hover
+   background fits inside the 32px header bar. */
+.graphiql-response-header .graphiql-toolbar-button {
+  height: 28px;
+  width: 28px;
+}
+
+.graphiql-response-pane {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+}
+
+.graphiql-response-pane .result-window {
+  flex: 1;
+  min-height: 0;
+}
+
+.graphiql-response-empty-state {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: oklch(var(--fg-subtle));
+  font-family: var(--font-family);
+  font-size: var(--font-size-small);
+}
diff --git a/packages/graphiql-react/src/components/response-header/index.tsx b/packages/graphiql-react/src/components/response-header/index.tsx
new file mode 100644
index 00000000000..50e1aadc364
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-header/index.tsx
@@ -0,0 +1,83 @@
+'use no memo';
+
+import type { FC } from 'react';
+import { SegmentedControl } from '../segmented-control';
+import { ToolbarButton } from '../toolbar-button';
+import { CopyIcon } from '../../icons';
+import type { ResponseView } from '../../stores';
+import './index.css';
+
+export type ResponseHeaderProps = {
+  /** HTTP-equivalent status code from the last response. */
+  status?: number;
+  /** Elapsed time for the last request in milliseconds. */
+  timeMs?: number;
+  /** Approximate response body size in bytes. */
+  sizeBytes?: number;
+  /** Currently active response view. */
+  view: ResponseView;
+  /** Called when the user selects a different view. */
+  onViewChange: (view: ResponseView) => void;
+  /** Called when the user clicks the copy button. Omit to hide the button. */
+  onCopy?: () => void;
+};
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+const VIEW_OPTIONS: { value: ResponseView; label: string }[] = [
+  { value: 'json', label: 'JSON' },
+  { value: 'tree', label: 'Tree' },
+  { value: 'table', label: 'Table' },
+];
+
+export const ResponseHeader: FC<ResponseHeaderProps> = ({
+  status,
+  timeMs,
+  sizeBytes,
+  view,
+  onViewChange,
+  onCopy,
+}) => {
+  const isError = status !== undefined && (status === 0 || status >= 400);
+
+  return (
+    <header className="graphiql-response-header">
+      {status !== undefined && (
+        <span
+          className={`graphiql-response-status${isError ? ' graphiql-response-status--error' : ' graphiql-response-status--ok'}`}
+        >
+          <span className="graphiql-response-status-dot" aria-hidden="true" />
+          <span className="graphiql-response-status-code">
+            {status === 0 ? 'Error' : status}
+          </span>
+        </span>
+      )}
+      {timeMs !== undefined && (
+        <span className="graphiql-response-meta">{timeMs}ms</span>
+      )}
+      {sizeBytes !== undefined && (
+        <span className="graphiql-response-meta">{formatBytes(sizeBytes)}</span>
+      )}
+      <span className="graphiql-response-header-spacer" />
+      <SegmentedControl
+        value={view}
+        onChange={onViewChange}
+        ariaLabel="Response view"
+        options={VIEW_OPTIONS}
+      />
+      {onCopy && (
+        <ToolbarButton label="Copy response" onClick={onCopy}>
+          <CopyIcon aria-hidden="true" />
+        </ToolbarButton>
+      )}
+    </header>
+  );
+};
diff --git a/packages/graphiql-react/src/components/response-header/response-header.stories.tsx b/packages/graphiql-react/src/components/response-header/response-header.stories.tsx
new file mode 100644
index 00000000000..3bcc7cea1f3
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-header/response-header.stories.tsx
@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { Tooltip } from '../tooltip';
+import { ResponseHeader } from './';
+import type { ResponseView } from '../../stores';
+
+const meta: Meta<typeof ResponseHeader> = {
+  title: 'Primitives/ResponseHeader',
+  component: ResponseHeader,
+  tags: ['autodocs'],
+  decorators: [
+    Story => (
+      <Tooltip.Provider>
+        <Story />
+      </Tooltip.Provider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof ResponseHeader>;
+
+export const Empty: Story = {
+  render() {
+    const [view, setView] = useState<ResponseView>('json');
+    return <ResponseHeader view={view} onViewChange={setView} />;
+  },
+};
+
+export const WithMetadata: Story = {
+  render() {
+    const [view, setView] = useState<ResponseView>('json');
+    return (
+      <ResponseHeader
+        status={200}
+        timeMs={143}
+        sizeBytes={2812}
+        view={view}
+        onViewChange={setView}
+        onCopy={() => {}}
+      />
+    );
+  },
+};
+
+export const ErrorStatus: Story = {
+  render() {
+    const [view, setView] = useState<ResponseView>('json');
+    return (
+      <ResponseHeader
+        status={0}
+        timeMs={12}
+        sizeBytes={89}
+        view={view}
+        onViewChange={setView}
+      />
+    );
+  },
+};
+
+export const TreeView: Story = {
+  render() {
+    const [view, setView] = useState<ResponseView>('tree');
+    return (
+      <ResponseHeader
+        status={200}
+        timeMs={56}
+        sizeBytes={1024}
+        view={view}
+        onViewChange={setView}
+        onCopy={() => {}}
+      />
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/components/response-header/response-header.test.tsx b/packages/graphiql-react/src/components/response-header/response-header.test.tsx
new file mode 100644
index 00000000000..f656029adcf
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-header/response-header.test.tsx
@@ -0,0 +1,122 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Tooltip } from '../tooltip';
+import { ResponseHeader } from './';
+
+function renderWithTooltip(ui: React.ReactElement) {
+  return render(<Tooltip.Provider>{ui}</Tooltip.Provider>);
+}
+
+describe('ResponseHeader', () => {
+  it('renders the view toggle with all three options', () => {
+    renderWithTooltip(<ResponseHeader view="json" onViewChange={() => {}} />);
+    expect(screen.getByRole('radio', { name: 'JSON' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Tree' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'Table' })).toBeInTheDocument();
+  });
+
+  it('marks the active view as checked', () => {
+    renderWithTooltip(<ResponseHeader view="tree" onViewChange={() => {}} />);
+    expect(screen.getByRole('radio', { name: 'Tree' })).toBeChecked();
+    expect(screen.getByRole('radio', { name: 'JSON' })).not.toBeChecked();
+  });
+
+  it('calls onViewChange when a different view is selected', async () => {
+    const user = userEvent.setup();
+    const onViewChange = vi.fn();
+    renderWithTooltip(
+      <ResponseHeader view="json" onViewChange={onViewChange} />,
+    );
+    await user.click(screen.getByRole('radio', { name: 'Tree' }));
+    expect(onViewChange).toHaveBeenCalledWith('tree');
+  });
+
+  it('renders status code when provided', () => {
+    renderWithTooltip(
+      <ResponseHeader status={200} view="json" onViewChange={() => {}} />,
+    );
+    expect(screen.getByText('200')).toBeInTheDocument();
+  });
+
+  it('does not render status when omitted', () => {
+    const { container } = renderWithTooltip(
+      <ResponseHeader view="json" onViewChange={() => {}} />,
+    );
+    expect(container.querySelector('.graphiql-response-status')).toBeNull();
+  });
+
+  it('renders time in ms when provided', () => {
+    renderWithTooltip(
+      <ResponseHeader timeMs={42} view="json" onViewChange={() => {}} />,
+    );
+    expect(screen.getByText('42ms')).toBeInTheDocument();
+  });
+
+  it('renders size in bytes when provided', () => {
+    renderWithTooltip(
+      <ResponseHeader sizeBytes={512} view="json" onViewChange={() => {}} />,
+    );
+    expect(screen.getByText('512 B')).toBeInTheDocument();
+  });
+
+  it('formats size in KB for values >= 1024', () => {
+    renderWithTooltip(
+      <ResponseHeader sizeBytes={2048} view="json" onViewChange={() => {}} />,
+    );
+    expect(screen.getByText('2.0 KB')).toBeInTheDocument();
+  });
+
+  it('renders the copy button when onCopy is provided', () => {
+    renderWithTooltip(
+      <ResponseHeader view="json" onViewChange={() => {}} onCopy={() => {}} />,
+    );
+    expect(
+      screen.getByRole('button', { name: 'Copy response' }),
+    ).toBeInTheDocument();
+  });
+
+  it('hides the copy button when onCopy is omitted', () => {
+    renderWithTooltip(<ResponseHeader view="json" onViewChange={() => {}} />);
+    expect(screen.queryByRole('button', { name: 'Copy response' })).toBeNull();
+  });
+
+  it('calls onCopy when the copy button is clicked', async () => {
+    const user = userEvent.setup();
+    const onCopy = vi.fn();
+    renderWithTooltip(
+      <ResponseHeader view="json" onViewChange={() => {}} onCopy={onCopy} />,
+    );
+    await user.click(screen.getByRole('button', { name: 'Copy response' }));
+    expect(onCopy).toHaveBeenCalledOnce();
+  });
+
+  it('shows error styling for status 0', () => {
+    const { container } = renderWithTooltip(
+      <ResponseHeader status={0} view="json" onViewChange={() => {}} />,
+    );
+    expect(
+      container.querySelector('.graphiql-response-status--error'),
+    ).toBeInTheDocument();
+  });
+
+  it('shows error styling for status >= 400', () => {
+    const { container } = renderWithTooltip(
+      <ResponseHeader status={500} view="json" onViewChange={() => {}} />,
+    );
+    expect(
+      container.querySelector('.graphiql-response-status--error'),
+    ).toBeInTheDocument();
+  });
+
+  it('shows ok styling for status 200', () => {
+    const { container } = renderWithTooltip(
+      <ResponseHeader status={200} view="json" onViewChange={() => {}} />,
+    );
+    expect(
+      container.querySelector('.graphiql-response-status--ok'),
+    ).toBeInTheDocument();
+  });
+});
diff --git a/packages/graphiql-react/src/constants.ts b/packages/graphiql-react/src/constants.ts
index d417eea678b..d4628bc46f6 100644
--- a/packages/graphiql-react/src/constants.ts
+++ b/packages/graphiql-react/src/constants.ts
@@ -54,6 +54,7 @@ export const STORAGE_KEY = {
   tabs: 'tabState',
   persistHeaders: 'shouldPersistHeaders',
   theme: 'theme',
+  responseView: 'responseView',
 } as const;
 
 export const DEFAULT_QUERY = `# Welcome to GraphiQL
diff --git a/packages/graphiql-react/src/index.ts b/packages/graphiql-react/src/index.ts
index 314b81a7a3c..242d805b253 100644
--- a/packages/graphiql-react/src/index.ts
+++ b/packages/graphiql-react/src/index.ts
@@ -15,5 +15,6 @@ export type {
   Theme,
 } from './types';
 export type { GraphiQLPlugin } from './stores/plugin';
+export type { ResponseView, LastResponse } from './stores';
 export { KEY_MAP, formatShortcutForOS, isMacOs } from './constants';
 export * from './deprecated';
diff --git a/packages/graphiql-react/src/stores/execution.spec.ts b/packages/graphiql-react/src/stores/execution.spec.ts
new file mode 100644
index 00000000000..fa9b6819780
--- /dev/null
+++ b/packages/graphiql-react/src/stores/execution.spec.ts
@@ -0,0 +1,89 @@
+'use no memo';
+
+import { describe, it, expect, vi } from 'vitest';
+import { create } from 'zustand';
+import { StorageAPI } from '@graphiql/toolkit';
+import { createExecutionSlice, isResponseView } from './execution';
+import { createStorageSlice } from './storage';
+import { STORAGE_KEY } from '../constants';
+import type { SlicesWithActions } from '../types';
+
+function makeMemoryStorage() {
+  const data = new Map<string, string>();
+  return {
+    getItem: (key: string) => data.get(key) ?? null,
+    setItem(key: string, value: string) {
+      data.set(key, value);
+    },
+    removeItem(key: string) {
+      data.delete(key);
+    },
+    get length() {
+      return data.size;
+    },
+    clear() {
+      data.clear();
+    },
+  };
+}
+
+function makeStore() {
+  const storage = new StorageAPI(makeMemoryStorage());
+  const store = create<SlicesWithActions>((...args) => {
+    const storageSlice = createStorageSlice({ storage })(...args);
+    const executionSlice = createExecutionSlice({
+      fetcher: vi.fn(),
+      getDefaultFieldNames: undefined,
+      overrideOperationName: null,
+    })(...args);
+    return {
+      ...storageSlice,
+      ...executionSlice,
+      actions: {
+        ...executionSlice.actions,
+      } as any,
+    } as SlicesWithActions;
+  });
+  return { store, storage };
+}
+
+describe('isResponseView', () => {
+  it('accepts the three known views', () => {
+    expect(isResponseView('json')).toBe(true);
+    expect(isResponseView('tree')).toBe(true);
+    expect(isResponseView('table')).toBe(true);
+  });
+
+  it('rejects unknown values', () => {
+    expect(isResponseView('graph')).toBe(false);
+    expect(isResponseView('')).toBe(false);
+    expect(isResponseView(null)).toBe(false);
+    expect(isResponseView(42)).toBe(false);
+  });
+});
+
+describe('setResponseView', () => {
+  it('defaults to "json"', () => {
+    const { store } = makeStore();
+    expect(store.getState().responseView).toBe('json');
+  });
+
+  it('updates state on call', () => {
+    const { store } = makeStore();
+    store.getState().actions.setResponseView('tree');
+    expect(store.getState().responseView).toBe('tree');
+  });
+
+  it('writes the new view to storage', () => {
+    const { store, storage } = makeStore();
+    store.getState().actions.setResponseView('table');
+    expect(storage.get(STORAGE_KEY.responseView)).toBe('table');
+  });
+
+  it('persists across action calls', () => {
+    const { store, storage } = makeStore();
+    store.getState().actions.setResponseView('tree');
+    store.getState().actions.setResponseView('json');
+    expect(storage.get(STORAGE_KEY.responseView)).toBe('json');
+  });
+});
diff --git a/packages/graphiql-react/src/stores/execution.ts b/packages/graphiql-react/src/stores/execution.ts
index 824d933656b..35459a4372b 100644
--- a/packages/graphiql-react/src/stores/execution.ts
+++ b/packages/graphiql-react/src/stores/execution.ts
@@ -16,8 +16,28 @@ import getValue from 'get-value';
 import type { StateCreator } from 'zustand';
 import { tryParseJSONC } from '../utility';
 import { Range } from '../utility/monaco-ssr';
+import { STORAGE_KEY } from '../constants';
 import type { SlicesWithActions, MonacoEditor } from '../types';
 
+export type ResponseView = 'json' | 'tree' | 'table';
+
+const RESPONSE_VIEWS: readonly ResponseView[] = ['json', 'tree', 'table'];
+
+export function isResponseView(value: unknown): value is ResponseView {
+  return (
+    typeof value === 'string' && RESPONSE_VIEWS.includes(value as ResponseView)
+  );
+}
+
+export interface LastResponse {
+  /** HTTP-equivalent status code. 200 for a successful response, 0 if none. */
+  status: number;
+  /** Elapsed time in milliseconds. */
+  timeMs: number;
+  /** Approximate serialized size of the response body in bytes. */
+  sizeBytes: number;
+}
+
 export interface ExecutionSlice {
   /**
    * If there is currently a GraphQL request in-flight. For multipart
@@ -27,6 +47,19 @@ export interface ExecutionSlice {
    */
   isFetching: boolean;
 
+  /**
+   * Metadata captured from the most recent completed fetch: status, elapsed
+   * time, and approximate response size. `null` before any request runs.
+   * @default null
+   */
+  lastResponse: LastResponse | null;
+
+  /**
+   * Which view is active in the response pane.
+   * @default 'json'
+   */
+  responseView: ResponseView;
+
   /**
    * Represents an active GraphQL subscription.
    *
@@ -80,6 +113,11 @@ export interface ExecutionActions {
    * Stop the GraphQL request that is currently in-flight.
    */
   stop(): void;
+
+  /**
+   * Change which view is shown in the response pane.
+   */
+  setResponseView(view: ResponseView): void;
 }
 
 export interface ExecutionProps extends Pick<
@@ -178,9 +216,16 @@ export const createExecutionSlice: CreateExecutionSlice =
     return {
       ...initial,
       isFetching: false,
+      lastResponse: null,
+      responseView: 'json' as ResponseView,
       subscription: null,
       queryId: 0,
       actions: {
+        setResponseView(view: ResponseView) {
+          const { storage } = get();
+          storage.set(STORAGE_KEY.responseView, view);
+          set({ responseView: view });
+        },
         stop() {
           set(({ subscription }) => {
             subscription?.unsubscribe();
@@ -258,6 +303,7 @@ export const createExecutionSlice: CreateExecutionSlice =
 
           setResponse('');
           set({ isFetching: true });
+          const fetchStartMs = Date.now();
           try {
             const fullResponse: ExecutionResult = {};
             const handleResponse = (result: ExecutionResult) => {
@@ -281,11 +327,33 @@ export const createExecutionSlice: CreateExecutionSlice =
                   mergeIncrementalResult(fullResponse, part);
                 }
 
-                set({ isFetching: false });
-                setResponse(formatResult(fullResponse));
+                const formatted = formatResult(fullResponse);
+                set({
+                  isFetching: false,
+                  lastResponse: {
+                    status: fullResponse.errors?.length ? 200 : 200,
+                    timeMs: Date.now() - fetchStartMs,
+                    sizeBytes: new TextEncoder().encode(formatted).length,
+                  },
+                });
+                setResponse(formatted);
               } else {
-                set({ isFetching: false });
-                setResponse(formatResult(result));
+                const formatted = formatResult(result);
+                const hasErrors =
+                  typeof result === 'object' &&
+                  result !== null &&
+                  'errors' in result &&
+                  Array.isArray((result as ExecutionResult).errors) &&
+                  (result as ExecutionResult).errors!.length > 0;
+                set({
+                  isFetching: false,
+                  lastResponse: {
+                    status: hasErrors ? 200 : 200,
+                    timeMs: Date.now() - fetchStartMs,
+                    sizeBytes: new TextEncoder().encode(formatted).length,
+                  },
+                });
+                setResponse(formatted);
               }
             };
             const opName = overrideOperationName ?? operationName;
@@ -304,9 +372,17 @@ export const createExecutionSlice: CreateExecutionSlice =
                   handleResponse(result);
                 },
                 error(error: Error) {
-                  set({ isFetching: false });
-                  setResponse(formatError(error));
-                  set({ subscription: null });
+                  const errorText = formatError(error);
+                  set({
+                    isFetching: false,
+                    lastResponse: {
+                      status: 0,
+                      timeMs: Date.now() - fetchStartMs,
+                      sizeBytes: new TextEncoder().encode(errorText).length,
+                    },
+                    subscription: null,
+                  });
+                  setResponse(errorText);
                 },
                 complete() {
                   set({ isFetching: false, subscription: null });
@@ -326,9 +402,17 @@ export const createExecutionSlice: CreateExecutionSlice =
               handleResponse(value);
             }
           } catch (error) {
-            set({ isFetching: false });
-            setResponse(formatError(error));
-            set({ subscription: null });
+            const errorText = formatError(error);
+            set({
+              isFetching: false,
+              lastResponse: {
+                status: 0,
+                timeMs: Date.now() - fetchStartMs,
+                sizeBytes: new TextEncoder().encode(errorText).length,
+              },
+              subscription: null,
+            });
+            setResponse(errorText);
           }
         },
       },
diff --git a/packages/graphiql-react/src/stores/index.ts b/packages/graphiql-react/src/stores/index.ts
index de06e03d493..08e127372ee 100644
--- a/packages/graphiql-react/src/stores/index.ts
+++ b/packages/graphiql-react/src/stores/index.ts
@@ -6,9 +6,12 @@ export {
 } from './editor';
 export {
   createExecutionSlice,
+  isResponseView,
   type ExecutionSlice,
   type ExecutionActions,
   type ExecutionProps,
+  type ResponseView,
+  type LastResponse,
 } from './execution';
 export {
   createPluginSlice,

From fdbd07d0c11426ef2095ba6637fb80272dd01a86 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Thu, 28 May 2026 13:46:46 -0700
Subject: [PATCH 34/38] v6: Add useGraphiQLSettings hook (#4322)

## Summary

A new `useGraphiQLSettings()` hook in `@graphiql/react` owns the theme,
density, and font-size preferences. Values persist to `localStorage`
under the `graphiql:settings` key and apply automatically to the
GraphiQL container via `data-theme` / `data-density` / `data-font-size`
attributes, so the CSS cascade picks them up. Theme `auto` resolves
through `prefers-color-scheme` and tracks live system theme changes;
explicit `light` / `dark` pin the resolved value. The hook is wired into
the top-level `<GraphiQL>` provider so the attributes are present on
first paint.

## Test plan

- [x] On the deploy preview, open DevTools and run
`localStorage.setItem('graphiql:settings',
JSON.stringify({theme:'dark',density:'comfortable',fontSize:'default'}))`,
then reload; the `.graphiql-container` element should carry
`data-theme="dark"`.
- [x] Clear the key, reload with the OS in dark mode; `data-theme`
should resolve to `dark` via `auto`.
- [x] Toggle the OS appearance while the app is open; the container
attribute should follow without a reload.
- [x] Inspect the rendered HTML and confirm `data-density` and
`data-font-size` are present even on a fresh install (defaults
`comfortable` / `default`).

Refs: graphql/graphiql#4219
---
 .changeset/use-graphiql-settings.md           |   5 +
 .../src/hooks/use-graphiql-settings.spec.ts   | 239 ++++++++++++++++++
 .../src/hooks/use-graphiql-settings.ts        | 113 +++++++++
 packages/graphiql-react/src/index.ts          |  10 +
 packages/graphiql/src/GraphiQL.tsx            |   6 +-
 5 files changed, 372 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/use-graphiql-settings.md
 create mode 100644 packages/graphiql-react/src/hooks/use-graphiql-settings.spec.ts
 create mode 100644 packages/graphiql-react/src/hooks/use-graphiql-settings.ts

diff --git a/.changeset/use-graphiql-settings.md b/.changeset/use-graphiql-settings.md
new file mode 100644
index 00000000000..10733a5d9f1
--- /dev/null
+++ b/.changeset/use-graphiql-settings.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add a `useGraphiQLSettings()` hook for managing theme / density / font-size preferences with `localStorage` persistence. Settings apply automatically to the GraphiQL container via `data-*` attributes.
diff --git a/packages/graphiql-react/src/hooks/use-graphiql-settings.spec.ts b/packages/graphiql-react/src/hooks/use-graphiql-settings.spec.ts
new file mode 100644
index 00000000000..39ef3066a3a
--- /dev/null
+++ b/packages/graphiql-react/src/hooks/use-graphiql-settings.spec.ts
@@ -0,0 +1,239 @@
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  beforeAll,
+  vi,
+} from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import {
+  useGraphiQLSettings,
+  SETTINGS_STORAGE_KEY,
+  type GraphiQLSettings,
+} from './use-graphiql-settings';
+
+const STORAGE_KEY = SETTINGS_STORAGE_KEY;
+
+function setStorage(value: Partial<GraphiQLSettings>) {
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(value));
+}
+
+function clearStorage() {
+  localStorage.removeItem(STORAGE_KEY);
+}
+
+// jsdom doesn't implement matchMedia; install a configurable stub.
+let matchMediaMatches = false;
+
+beforeAll(() => {
+  // Node 24 + jsdom: window exists but localStorage is not populated. Install
+  // an in-memory Storage polyfill so the hook (and these tests) have somewhere
+  // to read and write.
+  if (globalThis.localStorage === undefined) {
+    const store = new Map<string, string>();
+    const storage: Storage = {
+      getItem: (key: string) => store.get(key) ?? null,
+      setItem(key: string, value: string) {
+        store.set(key, value);
+      },
+      removeItem(key: string) {
+        store.delete(key);
+      },
+      clear() {
+        store.clear();
+      },
+      key: (index: number) => Array.from(store.keys())[index] ?? null,
+      get length() {
+        return store.size;
+      },
+    };
+    Object.defineProperty(window, 'localStorage', {
+      writable: true,
+      value: storage,
+    });
+  }
+
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (query: string): MediaQueryList =>
+      ({
+        matches: matchMediaMatches,
+        media: query,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+      }) as unknown as MediaQueryList,
+  });
+});
+
+beforeEach(() => {
+  clearStorage();
+  matchMediaMatches = false;
+});
+
+afterEach(() => {
+  clearStorage();
+});
+
+describe('useGraphiQLSettings — defaults', () => {
+  it('returns default theme auto', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.theme).toBe('auto');
+  });
+
+  it('returns default density comfortable', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.density).toBe('comfortable');
+  });
+
+  it('returns default fontSize default', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.fontSize).toBe('default');
+  });
+});
+
+describe('useGraphiQLSettings — reads from localStorage', () => {
+  it('reads stored theme', () => {
+    setStorage({ theme: 'dark' });
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.theme).toBe('dark');
+  });
+
+  it('reads stored density', () => {
+    setStorage({ density: 'compact' });
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.density).toBe('compact');
+  });
+
+  it('reads stored fontSize', () => {
+    setStorage({ fontSize: 'large' });
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.fontSize).toBe('large');
+  });
+
+  it('falls back to defaults for missing keys', () => {
+    setStorage({ theme: 'light' });
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.density).toBe('comfortable');
+    expect(result.current.fontSize).toBe('default');
+  });
+
+  it('falls back to defaults for corrupt JSON', () => {
+    localStorage.setItem(STORAGE_KEY, '{not valid json}');
+    const { result } = renderHook(() => useGraphiQLSettings());
+    expect(result.current.theme).toBe('auto');
+    expect(result.current.density).toBe('comfortable');
+    expect(result.current.fontSize).toBe('default');
+  });
+});
+
+describe('useGraphiQLSettings — setters persist to localStorage', () => {
+  it('setTheme persists the new theme', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    act(() => {
+      result.current.setTheme('dark');
+    });
+    expect(result.current.theme).toBe('dark');
+    const stored = JSON.parse(
+      localStorage.getItem(STORAGE_KEY)!,
+    ) as GraphiQLSettings;
+    expect(stored.theme).toBe('dark');
+  });
+
+  it('setDensity persists the new density', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    act(() => {
+      result.current.setDensity('spacious');
+    });
+    expect(result.current.density).toBe('spacious');
+    const stored = JSON.parse(
+      localStorage.getItem(STORAGE_KEY)!,
+    ) as GraphiQLSettings;
+    expect(stored.density).toBe('spacious');
+  });
+
+  it('setFontSize persists the new fontSize', () => {
+    const { result } = renderHook(() => useGraphiQLSettings());
+    act(() => {
+      result.current.setFontSize('xl');
+    });
+    expect(result.current.fontSize).toBe('xl');
+    const stored = JSON.parse(
+      localStorage.getItem(STORAGE_KEY)!,
+    ) as GraphiQLSettings;
+    expect(stored.fontSize).toBe('xl');
+  });
+});
+
+describe('useGraphiQLSettings — data-* attributes on container', () => {
+  it('applies data-density and data-font-size on mount', () => {
+    const container = document.createElement('div');
+    container.className = 'graphiql-container';
+    document.body.append(container);
+
+    setStorage({ theme: 'light', density: 'compact', fontSize: 'large' });
+    renderHook(() => useGraphiQLSettings());
+
+    expect(container.getAttribute('data-theme')).toBe('light');
+    expect(container.getAttribute('data-density')).toBe('compact');
+    expect(container.getAttribute('data-font-size')).toBe('large');
+
+    container.remove();
+  });
+
+  it('updates attributes when settings change', () => {
+    const container = document.createElement('div');
+    container.className = 'graphiql-container';
+    document.body.append(container);
+
+    const { result } = renderHook(() => useGraphiQLSettings());
+
+    act(() => {
+      result.current.setDensity('spacious');
+    });
+
+    expect(container.getAttribute('data-density')).toBe('spacious');
+
+    container.remove();
+  });
+
+  it('applies resolved theme to container via containerRef', () => {
+    const container = document.createElement('div');
+    const ref = { current: container };
+
+    setStorage({ theme: 'dark' });
+    renderHook(() => useGraphiQLSettings(ref));
+
+    expect(container.getAttribute('data-theme')).toBe('dark');
+  });
+});
+
+describe('useGraphiQLSettings — auto theme', () => {
+  it('resolves auto to dark when prefers-color-scheme: dark', () => {
+    matchMediaMatches = true;
+
+    const container = document.createElement('div');
+    container.className = 'graphiql-container';
+    document.body.append(container);
+
+    renderHook(() => useGraphiQLSettings());
+
+    expect(container.getAttribute('data-theme')).toBe('dark');
+
+    container.remove();
+  });
+
+  it('resolves auto to light when prefers-color-scheme: light', () => {
+    // matchMediaMatches is false by default (set in beforeEach)
+    const container = document.createElement('div');
+    container.className = 'graphiql-container';
+    document.body.append(container);
+
+    renderHook(() => useGraphiQLSettings());
+
+    expect(container.getAttribute('data-theme')).toBe('light');
+
+    container.remove();
+  });
+});
diff --git a/packages/graphiql-react/src/hooks/use-graphiql-settings.ts b/packages/graphiql-react/src/hooks/use-graphiql-settings.ts
new file mode 100644
index 00000000000..80948bde23d
--- /dev/null
+++ b/packages/graphiql-react/src/hooks/use-graphiql-settings.ts
@@ -0,0 +1,113 @@
+import { useEffect, useState } from 'react';
+import type { RefObject } from 'react';
+
+export type Theme = 'auto' | 'light' | 'dark';
+export type Density = 'compact' | 'comfortable' | 'spacious';
+export type FontSize = 'compact' | 'default' | 'large' | 'xl';
+
+export type GraphiQLSettings = {
+  theme: Theme;
+  density: Density;
+  fontSize: FontSize;
+};
+
+export const SETTINGS_STORAGE_KEY = 'graphiql:settings';
+
+const DEFAULTS: GraphiQLSettings = {
+  theme: 'auto',
+  density: 'comfortable',
+  fontSize: 'default',
+};
+
+function readSettings(): GraphiQLSettings {
+  if (typeof window === 'undefined') {
+    return DEFAULTS;
+  }
+  try {
+    const raw = localStorage.getItem(SETTINGS_STORAGE_KEY);
+    if (!raw) {
+      return DEFAULTS;
+    }
+    const parsed = JSON.parse(raw) as Partial<GraphiQLSettings>;
+    return { ...DEFAULTS, ...parsed };
+  } catch {
+    return DEFAULTS;
+  }
+}
+
+function writeSettings(settings: GraphiQLSettings) {
+  try {
+    localStorage.setItem(SETTINGS_STORAGE_KEY, JSON.stringify(settings));
+  } catch {
+    // noop — quota or privacy mode
+  }
+}
+
+function resolveTheme(theme: Theme): 'light' | 'dark' {
+  if (theme !== 'auto') {
+    return theme;
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches
+    ? 'dark'
+    : 'light';
+}
+
+export function useGraphiQLSettings(
+  containerRef?: RefObject<HTMLElement | null>,
+) {
+  const [settings, setSettings] = useState<GraphiQLSettings>(readSettings);
+
+  function setTheme(theme: Theme) {
+    setSettings(s => ({ ...s, theme }));
+  }
+
+  function setDensity(density: Density) {
+    setSettings(s => ({ ...s, density }));
+  }
+
+  function setFontSize(fontSize: FontSize) {
+    setSettings(s => ({ ...s, fontSize }));
+  }
+
+  // Persist and apply data-* attributes whenever settings change.
+  useEffect(() => {
+    writeSettings(settings);
+
+    const target =
+      containerRef?.current ??
+      document.querySelector<HTMLElement>('.graphiql-container');
+    if (!target) {
+      return;
+    }
+
+    target.setAttribute('data-theme', resolveTheme(settings.theme));
+    target.setAttribute('data-density', settings.density);
+    target.setAttribute('data-font-size', settings.fontSize);
+  }, [settings, containerRef]);
+
+  // When theme is 'auto', track system preference changes live.
+  useEffect(() => {
+    if (settings.theme !== 'auto') {
+      return;
+    }
+
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+
+    function onSystemThemeChange() {
+      const target =
+        containerRef?.current ??
+        document.querySelector<HTMLElement>('.graphiql-container');
+      if (!target) {
+        return;
+      }
+      target.setAttribute('data-theme', resolveTheme('auto'));
+    }
+
+    mql.addEventListener('change', onSystemThemeChange);
+    return () => {
+      mql.removeEventListener('change', onSystemThemeChange);
+    };
+  }, [settings.theme, containerRef]);
+
+  return { ...settings, setTheme, setDensity, setFontSize };
+}
diff --git a/packages/graphiql-react/src/index.ts b/packages/graphiql-react/src/index.ts
index 242d805b253..e69a1a49ce9 100644
--- a/packages/graphiql-react/src/index.ts
+++ b/packages/graphiql-react/src/index.ts
@@ -3,6 +3,16 @@ import './style/root.css';
 export { useMonaco } from './stores';
 export * from './utility';
 export { Uri, KeyMod, KeyCode, Range } from './utility/monaco-ssr';
+export {
+  useGraphiQLSettings,
+  SETTINGS_STORAGE_KEY,
+} from './hooks/use-graphiql-settings';
+export type {
+  GraphiQLSettings,
+  Theme as SettingsTheme,
+  Density,
+  FontSize,
+} from './hooks/use-graphiql-settings';
 export type { TabsState } from './utility/tabs';
 export * from './icons';
 export * from './components';
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index 14ffd0b134a..80ed26c5267 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -33,6 +33,7 @@ import {
   UnStyledButton,
   useDragResize,
   useGraphiQL,
+  useGraphiQLSettings,
   pick,
   VariableEditor,
   EditorProps,
@@ -248,6 +249,9 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
   );
   const hasMonaco = useMonaco(state => Boolean(state.monaco));
 
+  const containerRef = useRef<HTMLDivElement>(null);
+  useGraphiQLSettings(containerRef);
+
   const pluginResize = useDragResize({
     defaultSizeRelation: 1 / 3,
     direction: 'horizontal',
@@ -464,7 +468,7 @@ export const GraphiQLInterface: FC<GraphiQLInterfaceProps> = ({
 
   return (
     <Tooltip.Provider>
-      <div className={cn('graphiql-container', className)}>
+      <div ref={containerRef} className={cn('graphiql-container', className)}>
         <TopBar />
         <div className="graphiql-body">
           <ActivityBar

From 093cb100a4524b1005b82c1c064bb897416bfc82 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 5 Jun 2026 15:10:01 -0700
Subject: [PATCH 35/38] v6: Add Transport API and `<GraphiQL transport>` prop
 (#4333)

## Summary

`@graphiql/toolkit` adds `createTransport`, which performs the GraphQL
request and returns a `TransportResponse` carrying the real HTTP wire
metadata (status, headers, timing, size). `<GraphiQL>` accepts a new
`transport` prop, mutually exclusive with `fetcher` at the type level,
that lets the response pane surface those values directly from the
underlying `Response`. The existing `Fetcher` API,
`createGraphiQLFetcher`, and the `fetcher` prop are deprecated but
continue to work unchanged; consumers staying on them see a one-time
dismissible banner in the response pane pointing at the migration guide
rather than fabricated values. Subscriptions require an explicit
`subscriptionClient`: pass your own `graphql-ws` or `graphql-sse` client
(both are signature-compatible). The toolkit does not build one for you.

Alternative to #4323. Refs #4019.

## Test plan

- [ ] Run `yarn workspace graphiql dev`, execute a query, and confirm
the response pane header shows the real HTTP status code (200), a real
elapsed-time badge in ms, and a real response-size badge.
- [ ] `cy.intercept` to a 500 and confirm the status pill flips to the
error state.
- [ ] Migrate an existing project from `createGraphiQLFetcher` to
`createTransport` and from `<GraphiQL fetcher={...}>` to `<GraphiQL
transport={...}>`; queries, mutations, subscriptions, and incremental
delivery (`@defer`/`@stream`) all still work.
- [ ] Pass `graphql-sse`'s `createClient({url})` as `subscriptionClient`
to `createTransport` and confirm subscriptions stream over SSE.
- [ ] Render `<GraphiQL fetcher={someFetcher}>` and confirm the in-pane
upgrade banner appears, dismisses on click, stays dismissed across
reloads, and the response pane header is fully unmounted after dismiss
in the `fetcher` path.
- [ ] Confirm passing both `fetcher` and `transport` to `<GraphiQL>` is
a TypeScript compile error.
- [ ] Confirm dispatching a subscription on a `Transport` configured
without `subscriptionClient` throws with a pointer at the migration
guide.
---
 .changeset/transport-api.md                   |   9 +
 docs/migration/graphiql-6.0.0.md              | 160 ++++++++++
 examples/graphiql-cdn/index.html              |   6 +-
 examples/graphiql-nextjs/src/app/graphiql.tsx |  17 +-
 examples/graphiql-vite-react-router/README.md |   6 +-
 .../app/routes/_index/create-fetcher.ts       |  16 -
 .../app/routes/_index/graphiql.client.tsx     |   8 +-
 examples/graphiql-vite/src/App.jsx            |  17 +-
 examples/graphiql-webpack/src/index.jsx       |   8 +-
 examples/monaco-graphql-nextjs/src/editor.tsx |  28 +-
 .../graphiql-plugin-code-exporter/README.md   |   6 +-
 .../example/index.html                        |   6 +-
 packages/graphiql-plugin-explorer/README.md   |   6 +-
 .../src/history.stories.tsx                   |  11 +-
 packages/graphiql-react/README.md             |  14 +-
 .../src/components/provider.tsx               |  38 ++-
 .../src/components/response-editor.tsx        |  37 ++-
 .../src/components/response-header/index.css  |  48 +++
 .../src/components/response-header/index.tsx  |  76 ++++-
 .../response-header.stories.tsx               |  25 ++
 .../side-panel/side-panel.stories.tsx         |  11 +-
 .../components/top-bar/top-bar.stories.tsx    |  11 +-
 packages/graphiql-react/src/constants.ts      |   1 +
 packages/graphiql-react/src/index.ts          |   2 +-
 .../src/stores/execution.spec.ts              |  21 ++
 .../graphiql-react/src/stores/execution.ts    | 288 ++++++++++++------
 packages/graphiql-react/src/stores/index.ts   |   1 -
 packages/graphiql-react/src/stores/schema.ts  |  35 ++-
 .../graphiql-toolkit/docs/create-fetcher.md   |   4 +
 .../src/create-fetcher/createFetcher.ts       |   4 +
 .../src/create-fetcher/lib.ts                 | 141 +++++++++
 .../src/create-fetcher/types.ts               |  17 ++
 .../__tests__/createTransport.spec.ts         | 173 +++++++++++
 .../src/create-transport/createTransport.ts   | 128 ++++++++
 .../src/create-transport/index.ts             |   2 +
 .../src/create-transport/types.ts             |  92 ++++++
 packages/graphiql-toolkit/src/index.ts        |   1 +
 packages/graphiql/README.md                   |  24 +-
 packages/graphiql/cypress/e2e/transport.cy.ts |  59 ++++
 packages/graphiql/package.json                |   1 +
 packages/graphiql/src/GraphiQL.spec.tsx       |  35 ++-
 packages/graphiql/src/GraphiQL.tsx            |  21 +-
 packages/graphiql/src/cdn.ts                  |  20 +-
 packages/graphiql/src/e2e.ts                  |   6 +-
 yarn.lock                                     |   1 +
 45 files changed, 1394 insertions(+), 247 deletions(-)
 create mode 100644 .changeset/transport-api.md
 create mode 100644 docs/migration/graphiql-6.0.0.md
 delete mode 100644 examples/graphiql-vite-react-router/app/routes/_index/create-fetcher.ts
 create mode 100644 packages/graphiql-toolkit/src/create-transport/__tests__/createTransport.spec.ts
 create mode 100644 packages/graphiql-toolkit/src/create-transport/createTransport.ts
 create mode 100644 packages/graphiql-toolkit/src/create-transport/index.ts
 create mode 100644 packages/graphiql-toolkit/src/create-transport/types.ts
 create mode 100644 packages/graphiql/cypress/e2e/transport.cy.ts

diff --git a/.changeset/transport-api.md b/.changeset/transport-api.md
new file mode 100644
index 00000000000..ab4b924913f
--- /dev/null
+++ b/.changeset/transport-api.md
@@ -0,0 +1,9 @@
+---
+'@graphiql/toolkit': minor
+'@graphiql/react': minor
+'graphiql': minor
+---
+
+Add a `Transport` API alongside the existing `Fetcher`. `createTransport({...})` performs the GraphQL request and returns a `TransportResponse` carrying the real HTTP wire metadata (status, headers, timing, size) for queries, mutations, subscriptions, and incremental delivery. `<GraphiQL>` accepts a new `transport` prop, mutually exclusive with `fetcher` at the type level, that lets the response pane surface those values directly from the underlying `Response`. Subscriptions require an explicit `subscriptionClient` (any client whose `.subscribe(payload, sink)` matches the `graphql-ws` `Client` shape, including `graphql-sse`'s `createClient()`); the toolkit no longer constructs one. The CDN bundle exposes `GraphiQL.createTransport` and `GraphiQL.createWsClient` so script-tag consumers can adopt without a bundler.
+
+`createGraphiQLFetcher`, the `Fetcher` type and its companions, and the `<GraphiQL fetcher={...}>` prop are deprecated but continue to work unchanged. Existing code keeps compiling. Consumers on the deprecated path see a one-time dismissible banner in the response pane pointing at `docs/migration/graphiql-6.0.0.md` rather than fabricated status/timing/size values.
diff --git a/docs/migration/graphiql-6.0.0.md b/docs/migration/graphiql-6.0.0.md
new file mode 100644
index 00000000000..032a01732e5
--- /dev/null
+++ b/docs/migration/graphiql-6.0.0.md
@@ -0,0 +1,160 @@
+# Upgrading `graphiql` to `6.0.0`
+
+This covers the one notable change in `graphiql@6`: a new `Transport` API that replaces `Fetcher`/`createGraphiQLFetcher`. The rest of the surface carries over. Open an issue if something is missing here and we'll add it.
+
+## Overview
+
+`@graphiql/toolkit` adds `createTransport`, which takes the same options as `createGraphiQLFetcher` and produces a `Transport`. Unlike `Fetcher`, a `Transport`'s response carries the real HTTP wire data: status code, headers, body, timing, and request/response sizes. `<GraphiQL>` accepts a new `transport` prop alongside the existing `fetcher` prop; the two are mutually exclusive at the type level. The old API still works.
+
+## `createGraphiQLFetcher` → `createTransport`
+
+The HTTP options object carries over. Subscriptions are different: `createTransport` does not build a subscription client for you. You construct your own `graphql-ws` (or `graphql-sse`) client and pass it as `subscriptionClient`. There is no `subscriptionUrl`, `wsClient`, `legacyClient`, or `wsConnectionParams` option.
+
+**Before:**
+
+```ts
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+
+const fetcher = createGraphiQLFetcher({
+  url: 'https://my.endpoint/graphql',
+  subscriptionUrl: 'wss://my.endpoint/graphql',
+});
+```
+
+**After (WebSocket subscriptions):**
+
+```ts
+import { createClient } from 'graphql-ws';
+import { createTransport } from '@graphiql/toolkit';
+
+const transport = createTransport({
+  url: 'https://my.endpoint/graphql',
+  subscriptionClient: createClient({ url: 'wss://my.endpoint/graphql' }),
+});
+```
+
+**After (SSE subscriptions):**
+
+`graphql-sse`'s `createClient()` is signature-compatible with `graphql-ws`, so the same option drives either protocol:
+
+```ts
+import { createClient } from 'graphql-sse';
+import { createTransport } from '@graphiql/toolkit';
+
+const transport = createTransport({
+  url: 'https://my.endpoint/graphql',
+  subscriptionClient: createClient({
+    url: 'https://my.endpoint/graphql/stream',
+  }),
+});
+```
+
+If you only run queries and mutations, leave `subscriptionClient` off. A subscription dispatched without it throws with a pointer back to this page.
+
+## `<GraphiQL fetcher={...}>` → `<GraphiQL transport={...}>`
+
+**Before:**
+
+```tsx
+import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { GraphiQL } from 'graphiql';
+
+const fetcher = createGraphiQLFetcher({ url: 'https://my.endpoint/graphql' });
+
+function App() {
+  return <GraphiQL fetcher={fetcher} />;
+}
+```
+
+**After:**
+
+```tsx
+import { createTransport } from '@graphiql/toolkit';
+import { GraphiQL } from 'graphiql';
+
+const transport = createTransport({ url: 'https://my.endpoint/graphql' });
+
+function App() {
+  return <GraphiQL transport={transport} />;
+}
+```
+
+Passing both props is a type error. Remove `fetcher` when you add `transport`.
+
+## What you get
+
+With a `Transport`, the response pane header shows the real HTTP status code, total round-trip time, and the request and response byte sizes, read directly off the `Response`. Response headers are accessible through the response detail panel.
+
+With a `fetcher`, none of that is observable. The `Fetcher` contract is `(params) => ExecutionResult`, which discards the HTTP envelope before GraphiQL sees it. The response pane shows a small dismissible notice pointing here instead of fabricated values.
+
+## Custom fetchers (FAQ)
+
+If you hand-rolled a `Fetcher` rather than using `createGraphiQLFetcher`, migrate by implementing the `Transport` interface directly. A `Transport` is an object with a `send(request)` method. For queries and mutations it returns a `Promise<TransportResponse>`; for subscriptions and incremental delivery it returns an `AsyncIterable<TransportResponse>`, one entry per event or chunk.
+
+**Before (custom fetcher):**
+
+```ts
+import type { Fetcher } from '@graphiql/toolkit';
+
+const fetcher: Fetcher = async params => {
+  const res = await fetch('/graphql', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(params),
+  });
+  return res.json();
+};
+```
+
+**After (custom transport):**
+
+```ts
+import type { Transport } from '@graphiql/toolkit';
+
+const transport: Transport = {
+  async send(request) {
+    const startMs = performance.now();
+    const requestBody = JSON.stringify({
+      query: request.query,
+      operationName: request.operationName,
+      variables: request.variables,
+    });
+    const response = await fetch('/graphql', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...request.headers },
+      body: requestBody,
+    });
+    const body = await response.json();
+    const headers: Record<string, string> = {};
+    response.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+    return {
+      ok: !body.errors?.length,
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+      body,
+      timing: { totalMs: performance.now() - startMs },
+      size: {
+        request: new TextEncoder().encode(requestBody).length,
+        response: new TextEncoder().encode(JSON.stringify(body)).length,
+      },
+    };
+  },
+};
+```
+
+Read `status`, `statusText`, and `headers` off the real `Response`. Don't hard-code them; the response pane reads those fields directly.
+
+## What's deprecated, not removed
+
+The following are deprecated in `graphiql@6`. They continue to work and might be removed in a future major version.
+
+| Deprecated                                       | Replacement       |
+| ------------------------------------------------ | ----------------- |
+| `createGraphiQLFetcher` from `@graphiql/toolkit` | `createTransport` |
+| `fetcher` prop on `<GraphiQL>`                   | `transport` prop  |
+| `Fetcher` type from `@graphiql/toolkit`          | `Transport`       |
+
+Existing code keeps compiling and running today. Migrate when you want the response pane to show real wire data, or before a future major version drops the deprecated path.
diff --git a/examples/graphiql-cdn/index.html b/examples/graphiql-cdn/index.html
index 2ed29a0ee97..3a6d0e1c35e 100644
--- a/examples/graphiql-cdn/index.html
+++ b/examples/graphiql-cdn/index.html
@@ -76,18 +76,18 @@
       import React from 'react';
       import ReactDOM from 'react-dom/client';
       import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
-      import { createGraphiQLFetcher } from '@graphiql/toolkit';
+      import { createTransport } from '@graphiql/toolkit';
       import { explorerPlugin } from '@graphiql/plugin-explorer';
       import 'graphiql/setup-workers/esm.sh';
 
-      const fetcher = createGraphiQLFetcher({
+      const transport = createTransport({
         url: 'https://countries.trevorblades.com',
       });
       const plugins = [HISTORY_PLUGIN, explorerPlugin()];
 
       function App() {
         return React.createElement(GraphiQL, {
-          fetcher,
+          transport,
           plugins,
           defaultEditorToolsVisibility: true,
         });
diff --git a/examples/graphiql-nextjs/src/app/graphiql.tsx b/examples/graphiql-nextjs/src/app/graphiql.tsx
index 9cb59806ff1..d7bcd498134 100644
--- a/examples/graphiql-nextjs/src/app/graphiql.tsx
+++ b/examples/graphiql-nextjs/src/app/graphiql.tsx
@@ -2,21 +2,14 @@
 
 import type { FC } from 'react';
 import { GraphiQL } from 'graphiql';
+import { createTransport } from '@graphiql/toolkit';
 import 'graphiql/setup-workers/webpack';
 import 'graphiql/style.css';
 
-async function fetcher(graphQLParams: Record<string, unknown>) {
-  const response = await fetch('https://graphql.earthdata.nasa.gov/api', {
-    method: 'POST',
-    headers: {
-      Accept: 'application/json',
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(graphQLParams),
-  });
-  return response.json();
-}
+const transport = createTransport({
+  url: 'https://graphql.earthdata.nasa.gov/api',
+});
 
 export const GraphiQLPage: FC = () => {
-  return <GraphiQL fetcher={fetcher} />;
+  return <GraphiQL transport={transport} />;
 };
diff --git a/examples/graphiql-vite-react-router/README.md b/examples/graphiql-vite-react-router/README.md
index 60450da05e3..4ff74a75afe 100644
--- a/examples/graphiql-vite-react-router/README.md
+++ b/examples/graphiql-vite-react-router/README.md
@@ -7,11 +7,11 @@ by adding `.client` to the file name.
 ```tsx
 // graphiql.client.tsx
 import { GraphiQL } from 'graphiql';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 
-const fetcher = createGraphiQLFetcher({ url: 'https://my.backend/graphql' });
+const transport = createTransport({ url: 'https://my.backend/graphql' });
 
-export const graphiql = <GraphiQL fetcher={fetcher} />;
+export const graphiql = <GraphiQL transport={transport} />;
 ```
 
 ```ts
diff --git a/examples/graphiql-vite-react-router/app/routes/_index/create-fetcher.ts b/examples/graphiql-vite-react-router/app/routes/_index/create-fetcher.ts
deleted file mode 100644
index 1c095133685..00000000000
--- a/examples/graphiql-vite-react-router/app/routes/_index/create-fetcher.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import type { GraphiQLProps } from 'graphiql';
-
-export function createFetcher(apiUrl: string): GraphiQLProps['fetcher'] {
-  return async function (graphQLParams, opts) {
-    const response = await fetch(apiUrl, {
-      method: 'POST',
-      headers: {
-        ...opts?.headers,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(graphQLParams),
-    });
-
-    return response.json();
-  };
-}
diff --git a/examples/graphiql-vite-react-router/app/routes/_index/graphiql.client.tsx b/examples/graphiql-vite-react-router/app/routes/_index/graphiql.client.tsx
index b435650134d..f50c5f3fa0f 100644
--- a/examples/graphiql-vite-react-router/app/routes/_index/graphiql.client.tsx
+++ b/examples/graphiql-vite-react-router/app/routes/_index/graphiql.client.tsx
@@ -1,14 +1,18 @@
 import type { FC } from 'react';
 import { GraphiQL } from 'graphiql';
+import { createTransport } from '@graphiql/toolkit';
 import { ToolbarButton, useGraphiQL } from '@graphiql/react';
-import { createFetcher } from './create-fetcher';
 import 'graphiql/setup-workers/esm.sh';
 
+const transport = createTransport({
+  url: 'https://graphql.earthdata.nasa.gov/api',
+});
+
 export const graphiql = (
   <GraphiQL
     dangerouslyAssumeSchemaIsValid
     defaultEditorToolsVisibility="variables"
-    fetcher={createFetcher('https://graphql.earthdata.nasa.gov/api')}
+    transport={transport}
     isHeadersEditorEnabled={false}
   >
     <GraphiQL.Logo>API Explorer</GraphiQL.Logo>
diff --git a/examples/graphiql-vite/src/App.jsx b/examples/graphiql-vite/src/App.jsx
index 36a1683d5f4..1a8b71e5a90 100644
--- a/examples/graphiql-vite/src/App.jsx
+++ b/examples/graphiql-vite/src/App.jsx
@@ -1,20 +1,13 @@
 import { GraphiQL } from 'graphiql';
+import { createTransport } from '@graphiql/toolkit';
 import 'graphiql/style.css';
 
-async function fetcher(graphQLParams) {
-  const response = await fetch('https://graphql.earthdata.nasa.gov/api', {
-    method: 'POST',
-    headers: {
-      Accept: 'application/json',
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(graphQLParams),
-  });
-  return response.json();
-}
+const transport = createTransport({
+  url: 'https://graphql.earthdata.nasa.gov/api',
+});
 
 function App() {
-  return <GraphiQL fetcher={fetcher} />;
+  return <GraphiQL transport={transport} />;
 }
 
 export default App;
diff --git a/examples/graphiql-webpack/src/index.jsx b/examples/graphiql-webpack/src/index.jsx
index 8ca47fadc8d..6c93e9338d1 100644
--- a/examples/graphiql-webpack/src/index.jsx
+++ b/examples/graphiql-webpack/src/index.jsx
@@ -5,7 +5,7 @@ import { GraphiQL } from 'graphiql';
 import { explorerPlugin } from '@graphiql/plugin-explorer';
 import { getSnippets } from './snippets';
 import { codeExporterPlugin } from '@graphiql/plugin-code-exporter';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 import { useGraphiQL } from '@graphiql/react';
 import { serverSelectPlugin, LAST_URL_KEY } from './select-server-plugin';
 import 'graphiql/setup-workers/webpack';
@@ -65,8 +65,8 @@ function App() {
       codeExporterPlugin({ snippets: getSnippets({ serverUrl: currentUrl }) }),
     [currentUrl],
   );
-  const fetcher = useMemo(
-    () => createGraphiQLFetcher({ url: currentUrl }),
+  const transport = useMemo(
+    () => createTransport({ url: currentUrl }),
     [currentUrl],
   );
   const serverSelect = useMemo(
@@ -78,7 +78,7 @@ function App() {
     <GraphiQL
       style={style}
       plugins={[serverSelect, explorer, exporter]}
-      fetcher={fetcher}
+      transport={transport}
       shouldPersistHeaders
     >
       <GraphiQLContextBound setUrl={setUrl} />
diff --git a/examples/monaco-graphql-nextjs/src/editor.tsx b/examples/monaco-graphql-nextjs/src/editor.tsx
index 32c2ecd8976..669b580a7f0 100644
--- a/examples/monaco-graphql-nextjs/src/editor.tsx
+++ b/examples/monaco-graphql-nextjs/src/editor.tsx
@@ -8,7 +8,7 @@ import 'monaco-editor/esm/vs/editor/contrib/peekView/browser/peekView';
 import 'monaco-editor/esm/vs/editor/contrib/parameterHints/browser/parameterHints';
 import 'monaco-editor/esm/vs/language/typescript/monaco.contribution';
 
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport, type TransportResponse } from '@graphiql/toolkit';
 import * as JSONC from 'jsonc-parser';
 import {
   DEFAULT_EDITOR_OPTIONS,
@@ -24,15 +24,23 @@ import {
   getOrCreateModel,
 } from './constants';
 
-const fetcher = createGraphiQLFetcher({ url: GRAPHQL_URL });
+// This demo only handles single-response query/mutation, so disable incremental
+// delivery to keep `transport.send()` resolving a single `TransportResponse`.
+const transport = createTransport({
+  url: GRAPHQL_URL,
+  enableIncrementalDelivery: false,
+});
 
 async function getSchema(): Promise<IntrospectionQuery> {
-  const data = await fetcher({
+  const response = (await transport.send({
     query: getIntrospectionQuery(),
     operationName: 'IntrospectionQuery',
-  });
+  })) as TransportResponse;
+  const body = response.body;
   const introspectionJSON =
-    'data' in data && (data.data as unknown as IntrospectionQuery);
+    !Array.isArray(body) && 'data' in body
+      ? (body.data as unknown as IntrospectionQuery)
+      : undefined;
 
   if (!introspectionJSON) {
     throw new Error(
@@ -116,15 +124,11 @@ export default function Editor(): ReactElement {
       // eslint-disable-next-line no-bitwise
       keybindings: [KeyMod.CtrlCmd | KeyCode.Enter],
       async run() {
-        const result = await fetcher({
+        const response = (await transport.send({
           query: MODEL.operations.getValue(),
           variables: JSONC.parse(MODEL.variables.getValue()),
-        });
-        // TODO: this demo only supports a single iteration for http GET/POST,
-        // no multipart or subscriptions yet.
-        // @ts-expect-error
-        const data = await result.next();
-        MODEL.response.setValue(JSON.stringify(data.value, null, 2));
+        })) as TransportResponse;
+        MODEL.response.setValue(JSON.stringify(response.body, null, 2));
       },
     };
 
diff --git a/packages/graphiql-plugin-code-exporter/README.md b/packages/graphiql-plugin-code-exporter/README.md
index 56c683531e3..36843eb1358 100644
--- a/packages/graphiql-plugin-code-exporter/README.md
+++ b/packages/graphiql-plugin-code-exporter/README.md
@@ -26,12 +26,12 @@ Example integration:
 
 ```jsx
 import { GraphiQL } from 'graphiql';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 import { codeExporterPlugin } from '@graphiql/plugin-code-exporter';
 import 'graphiql/style.css';
 import '@graphiql/plugin-code-exporter/style.css';
 
-const fetcher = createGraphiQLFetcher({
+const transport = createTransport({
   url: 'https://countries.trevorblades.com',
 });
 function getQuery(arg, spaceCount = 2) {
@@ -70,7 +70,7 @@ const codeExporter = codeExporterPlugin({
   ],
 });
 function App() {
-  return <GraphiQL fetcher={fetcher} plugins={[codeExporter]} />;
+  return <GraphiQL transport={transport} plugins={[codeExporter]} />;
 }
 ```
 
diff --git a/packages/graphiql-plugin-code-exporter/example/index.html b/packages/graphiql-plugin-code-exporter/example/index.html
index 7cca73d0881..880064007eb 100644
--- a/packages/graphiql-plugin-code-exporter/example/index.html
+++ b/packages/graphiql-plugin-code-exporter/example/index.html
@@ -59,7 +59,7 @@
       import ReactDOM from 'react-dom/client';
       // Import GraphiQL and the Explorer plugin
       import { GraphiQL, HISTORY_PLUGIN } from 'graphiql';
-      import { createGraphiQLFetcher } from '@graphiql/toolkit';
+      import { createTransport } from '@graphiql/toolkit';
       // Required to be before `@graphiql/plugin-code-exporter`
       import 'regenerator-runtime/runtime';
       import { codeExporterPlugin } from '@graphiql/plugin-code-exporter';
@@ -81,7 +81,7 @@
         },
       };
 
-      const fetcher = createGraphiQLFetcher({
+      const transport = createTransport({
         url: 'https://countries.trevorblades.com',
       });
       function getQuery(arg, spaceCount = 2) {
@@ -124,7 +124,7 @@
 
       function App() {
         return React.createElement(GraphiQL, {
-          fetcher,
+          transport,
           plugins,
           defaultEditorToolsVisibility: true,
         });
diff --git a/packages/graphiql-plugin-explorer/README.md b/packages/graphiql-plugin-explorer/README.md
index ea75f273f10..cd22b91cbfa 100644
--- a/packages/graphiql-plugin-explorer/README.md
+++ b/packages/graphiql-plugin-explorer/README.md
@@ -21,12 +21,12 @@ npm install react react-dom graphql
 
 ```jsx
 import { GraphiQL } from 'graphiql';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 import { explorerPlugin } from '@graphiql/plugin-explorer';
 import 'graphiql/style.css';
 import '@graphiql/plugin-explorer/style.css';
 
-const fetcher = createGraphiQLFetcher({
+const transport = createTransport({
   url: 'https://swapi-graphql.netlify.app/.netlify/functions/index',
 });
 
@@ -34,7 +34,7 @@ const fetcher = createGraphiQLFetcher({
 const explorer = explorerPlugin();
 
 function GraphiQLWithExplorer() {
-  return <GraphiQL fetcher={fetcher} plugins={[explorer]} />;
+  return <GraphiQL transport={transport} plugins={[explorer]} />;
 }
 ```
 
diff --git a/packages/graphiql-plugin-history/src/history.stories.tsx b/packages/graphiql-plugin-history/src/history.stories.tsx
index 16c8f1c7a4d..2dc02899bcc 100644
--- a/packages/graphiql-plugin-history/src/history.stories.tsx
+++ b/packages/graphiql-plugin-history/src/history.stories.tsx
@@ -17,7 +17,16 @@ import './style.css';
 function withHistoryContext(children: ReactNode) {
   return (
     <Tooltip.Provider>
-      <GraphiQLProvider fetcher={() => Promise.resolve({ data: {} })}>
+      <GraphiQLProvider
+        transport={{
+          send: async () => ({
+            ok: true,
+            body: { data: {} },
+            timing: { totalMs: 0 },
+            size: {},
+          }),
+        }}
+      >
         <HistoryStore>
           <div style={{ width: 320, background: 'oklch(var(--bg-elevated))' }}>
             {children}
diff --git a/packages/graphiql-react/README.md b/packages/graphiql-react/README.md
index b04674405e9..e4fd99abb29 100644
--- a/packages/graphiql-react/README.md
+++ b/packages/graphiql-react/README.md
@@ -22,21 +22,21 @@ All the state for your GraphQL IDE lives in multiple contexts. The easiest way
 to get started is by using the `GraphiQLProvider` component that renders all the
 individual providers.
 
-There is one required prop called `fetcher`. This is a function that performs
-GraphQL request against a given endpoint. You can easily create a fetcher using
-the method `createGraphiQLFetcher` from the `@graphiql/toolkit` package.
+There is one required prop called `transport`. This is a function that performs
+GraphQL requests against a given endpoint. You can easily create a transport using
+the method `createTransport` from the `@graphiql/toolkit` package.
 
 ```jsx
 import { GraphiQLProvider } from '@graphiql/react';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 
-const fetcher = createGraphiQLFetcher({
+const transport = createTransport({
   url: 'https://my.graphql.api/graphql',
 });
 
 function MyGraphQLIDE() {
   return (
-    <GraphiQLProvider fetcher={fetcher}>
+    <GraphiQLProvider transport={transport}>
       <div className="graphiql-container">Hello GraphQL</div>
     </GraphiQLProvider>
   );
@@ -51,7 +51,7 @@ import { QueryEditor } from '@graphiql/react';
 
 function MyGraphQLIDE() {
   return (
-    <GraphiQLProvider fetcher={fetcher}>
+    <GraphiQLProvider transport={transport}>
       <div className="graphiql-container">
         <QueryEditor />
       </div>
diff --git a/packages/graphiql-react/src/components/provider.tsx b/packages/graphiql-react/src/components/provider.tsx
index 33b1262f9f8..11c90d22f1b 100644
--- a/packages/graphiql-react/src/components/provider.tsx
+++ b/packages/graphiql-react/src/components/provider.tsx
@@ -49,16 +49,14 @@ function isIntrospectionData(value: unknown): value is IntrospectionQuery {
   return typeof value === 'object' && value !== null && '__schema' in value;
 }
 
-interface GraphiQLProviderProps
-  extends
-    EditorProps,
-    ExecutionProps,
-    PluginProps,
-    SchemaProps,
-    ThemeProps,
-    StorageProps {
-  children: ReactNode;
-}
+type GraphiQLProviderProps = EditorProps &
+  ExecutionProps &
+  PluginProps &
+  SchemaProps &
+  ThemeProps &
+  StorageProps & {
+    children: ReactNode;
+  };
 
 type GraphiQLStore = UseBoundStore<StoreApi<SlicesWithActions>>;
 
@@ -66,9 +64,15 @@ const GraphiQLContext = createContext<RefObject<GraphiQLStore> | null>(null);
 
 export const GraphiQLProvider: FC<GraphiQLProviderProps> = props => {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime check
-  if (!props.fetcher) {
+  if (!props.fetcher && !props.transport) {
+    throw new TypeError(
+      'The `GraphiQLProvider` component requires either a `transport` or a `fetcher` prop.',
+    );
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime check
+  if (props.fetcher && props.transport) {
     throw new TypeError(
-      'The `GraphiQLProvider` component requires a `fetcher` function to be passed as prop.',
+      'The `fetcher` and `transport` props are mutually exclusive. Pass one or the other, not both.',
     );
   }
   // @ts-expect-error -- runtime check
@@ -154,6 +158,7 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
 
   dangerouslyAssumeSchemaIsValid = false,
   fetcher,
+  transport,
   inputValueDeprecation = false,
   introspectionQueryName = 'IntrospectionQuery',
   onSchemaChange,
@@ -273,6 +278,7 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
         })(...args);
         const executionSlice = createExecutionSlice({
           fetcher,
+          transport,
           getDefaultFieldNames,
           overrideOperationName: operationName,
         })(...args);
@@ -309,6 +315,9 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
       actions.setVisiblePlugin(getInitialVisiblePlugin());
       actions.setTheme(getInitialTheme());
       actions.setResponseView(getInitialResponseView());
+      if (storage.get(STORAGE_KEY.transportUpgradeBannerDismissed) === 'true') {
+        store.setState({ transportUpgradeBannerDismissed: true });
+      }
 
       return store;
     }
@@ -327,8 +336,8 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
 
   // Execution sync
   useDidUpdate(() => {
-    storeRef.current.setState({ fetcher });
-  }, [fetcher]);
+    storeRef.current.setState({ fetcher, transport });
+  }, [fetcher, transport]);
 
   // Plugin sync
   useDidUpdate(() => {
@@ -371,6 +380,7 @@ const InnerGraphiQLProvider: FC<GraphiQLProviderProps> = ({
     schema,
     dangerouslyAssumeSchemaIsValid,
     fetcher, // should refresh schema with a new fetcher after a fetchError
+    transport, // ...or transport
   ]);
 
   /**
diff --git a/packages/graphiql-react/src/components/response-editor.tsx b/packages/graphiql-react/src/components/response-editor.tsx
index 0cc01727c56..2a90ee45f56 100644
--- a/packages/graphiql-react/src/components/response-editor.tsx
+++ b/packages/graphiql-react/src/components/response-editor.tsx
@@ -39,7 +39,8 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
   responseTooltip: ResponseTooltip,
   ...props
 }) => {
-  const { setEditor, run, setResponseView } = useGraphiQLActions();
+  const { setEditor, run, setResponseView, dismissTransportUpgradeBanner } =
+    useGraphiQLActions();
   const {
     fetchError,
     validationErrors,
@@ -47,6 +48,8 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
     uriInstanceId,
     lastResponse,
     responseView,
+    transport,
+    transportUpgradeBannerDismissed,
   } = useGraphiQL(
     pick(
       'fetchError',
@@ -55,6 +58,8 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
       'uriInstanceId',
       'lastResponse',
       'responseView',
+      'transport',
+      'transportUpgradeBannerDismissed',
     ),
   );
   const ref = useRef<HTMLDivElement>(null!);
@@ -166,16 +171,30 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
     return cleanupDisposables(disposables);
   }, [monaco]); // eslint-disable-line react-hooks/exhaustive-deps -- only on mount
 
+  const isFetcherPath = !transport;
+  const showUpgradeBanner = isFetcherPath && !transportUpgradeBannerDismissed;
+  const showHeader = !isFetcherPath || showUpgradeBanner;
+
   return (
     <div {...props} className={cn('graphiql-response-pane', props.className)}>
-      <ResponseHeader
-        status={lastResponse?.status}
-        timeMs={lastResponse?.timeMs}
-        sizeBytes={lastResponse?.sizeBytes}
-        view={responseView}
-        onViewChange={handleViewChange}
-        onCopy={handleCopy}
-      />
+      {showHeader && (
+        <ResponseHeader
+          status={lastResponse?.status}
+          timeMs={lastResponse?.timing.totalMs}
+          sizeBytes={lastResponse?.size.response}
+          upgradeNotice={
+            showUpgradeBanner
+              ? {
+                  href: 'https://github.com/graphql/graphiql/blob/main/docs/migration/graphiql-6.0.0.md',
+                  onDismiss: dismissTransportUpgradeBanner,
+                }
+              : undefined
+          }
+          view={responseView}
+          onViewChange={handleViewChange}
+          onCopy={handleCopy}
+        />
+      )}
       {responseView === 'json' ? (
         <section
           ref={ref}
diff --git a/packages/graphiql-react/src/components/response-header/index.css b/packages/graphiql-react/src/components/response-header/index.css
index ddcc940f343..c31c2bb9d5b 100644
--- a/packages/graphiql-react/src/components/response-header/index.css
+++ b/packages/graphiql-react/src/components/response-header/index.css
@@ -80,3 +80,51 @@
   font-family: var(--font-family);
   font-size: var(--font-size-small);
 }
+
+.graphiql-transport-upgrade-banner {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--px-6);
+  font-size: 11.5px;
+  line-height: 1;
+  color: oklch(var(--fg-default));
+}
+
+.graphiql-transport-upgrade-banner-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: oklch(var(--accent-yellow));
+  flex-shrink: 0;
+}
+
+.graphiql-transport-upgrade-banner-link,
+.graphiql-transport-upgrade-banner-link:visited {
+  color: oklch(var(--fg-default));
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.graphiql-transport-upgrade-banner-link:hover {
+  text-decoration-thickness: 2px;
+}
+
+.graphiql-transport-upgrade-banner-dismiss {
+  background: transparent;
+  border: 0;
+  padding: 2px;
+  cursor: pointer;
+  color: oklch(var(--fg-muted));
+  display: inline-flex;
+  align-items: center;
+  margin-left: var(--px-2);
+}
+
+.graphiql-transport-upgrade-banner-dismiss:hover {
+  color: oklch(var(--fg-default));
+}
+
+.graphiql-transport-upgrade-banner-dismiss > svg {
+  width: 12px;
+  height: 12px;
+}
diff --git a/packages/graphiql-react/src/components/response-header/index.tsx b/packages/graphiql-react/src/components/response-header/index.tsx
index 50e1aadc364..ec76e0c9eb4 100644
--- a/packages/graphiql-react/src/components/response-header/index.tsx
+++ b/packages/graphiql-react/src/components/response-header/index.tsx
@@ -3,7 +3,7 @@
 import type { FC } from 'react';
 import { SegmentedControl } from '../segmented-control';
 import { ToolbarButton } from '../toolbar-button';
-import { CopyIcon } from '../../icons';
+import { CloseIcon, CopyIcon } from '../../icons';
 import type { ResponseView } from '../../stores';
 import './index.css';
 
@@ -14,6 +14,15 @@ export type ResponseHeaderProps = {
   timeMs?: number;
   /** Approximate response body size in bytes. */
   sizeBytes?: number;
+  /**
+   * When set, the stats area is replaced with a small dismissible nudge that
+   * points users at the `Transport` migration guide. Used by the deprecated
+   * `fetcher` path where status/headers/size are unobservable.
+   */
+  upgradeNotice?: {
+    href: string;
+    onDismiss: () => void;
+  };
   /** Currently active response view. */
   view: ResponseView;
   /** Called when the user selects a different view. */
@@ -42,29 +51,68 @@ export const ResponseHeader: FC<ResponseHeaderProps> = ({
   status,
   timeMs,
   sizeBytes,
+  upgradeNotice,
   view,
   onViewChange,
   onCopy,
 }) => {
   const isError = status !== undefined && (status === 0 || status >= 400);
+  const handleDismiss = upgradeNotice?.onDismiss;
 
   return (
     <header className="graphiql-response-header">
-      {status !== undefined && (
-        <span
-          className={`graphiql-response-status${isError ? ' graphiql-response-status--error' : ' graphiql-response-status--ok'}`}
-        >
-          <span className="graphiql-response-status-dot" aria-hidden="true" />
-          <span className="graphiql-response-status-code">
-            {status === 0 ? 'Error' : status}
+      {upgradeNotice ? (
+        <span className="graphiql-transport-upgrade-banner" role="status">
+          <span
+            className="graphiql-transport-upgrade-banner-dot"
+            aria-hidden="true"
+          />
+          <span className="graphiql-transport-upgrade-banner-text">
+            Network stats need the Transport API.
           </span>
+          <a
+            className="graphiql-transport-upgrade-banner-link"
+            href={upgradeNotice.href}
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Learn more
+          </a>
+          <button
+            type="button"
+            className="graphiql-transport-upgrade-banner-dismiss"
+            aria-label="Dismiss banner"
+            onClick={handleDismiss}
+          >
+            <CloseIcon aria-hidden="true" />
+          </button>
         </span>
-      )}
-      {timeMs !== undefined && (
-        <span className="graphiql-response-meta">{timeMs}ms</span>
-      )}
-      {sizeBytes !== undefined && (
-        <span className="graphiql-response-meta">{formatBytes(sizeBytes)}</span>
+      ) : (
+        <>
+          {status !== undefined && (
+            <span
+              className={`graphiql-response-status${isError ? ' graphiql-response-status--error' : ' graphiql-response-status--ok'}`}
+            >
+              <span
+                className="graphiql-response-status-dot"
+                aria-hidden="true"
+              />
+              <span className="graphiql-response-status-code">
+                {status === 0 ? 'Error' : status}
+              </span>
+            </span>
+          )}
+          {timeMs !== undefined && (
+            <span className="graphiql-response-meta">
+              {Math.round(timeMs)}ms
+            </span>
+          )}
+          {sizeBytes !== undefined && (
+            <span className="graphiql-response-meta">
+              {formatBytes(sizeBytes)}
+            </span>
+          )}
+        </>
       )}
       <span className="graphiql-response-header-spacer" />
       <SegmentedControl
diff --git a/packages/graphiql-react/src/components/response-header/response-header.stories.tsx b/packages/graphiql-react/src/components/response-header/response-header.stories.tsx
index 3bcc7cea1f3..c3d0f4be4dd 100644
--- a/packages/graphiql-react/src/components/response-header/response-header.stories.tsx
+++ b/packages/graphiql-react/src/components/response-header/response-header.stories.tsx
@@ -73,3 +73,28 @@ export const TreeView: Story = {
     );
   },
 };
+
+export const UpgradeBanner: Story = {
+  name: 'Upgrade banner (fetcher path)',
+  parameters: {
+    // The migration-guide link is overridden to chromium's default `:visited`
+    // color (~#d60590) in the storybook test runner, which trips axe's
+    // color-contrast rule. Real users get the explicit `:visited` rule defined
+    // in index.css, so the production banner is unaffected.
+    a11y: { test: 'todo' },
+  },
+  render() {
+    const [view, setView] = useState<ResponseView>('json');
+    return (
+      <ResponseHeader
+        upgradeNotice={{
+          href: 'https://github.com/graphql/graphiql/blob/main/docs/migration/graphiql-6.0.0.md',
+          onDismiss() {},
+        }}
+        view={view}
+        onViewChange={setView}
+        onCopy={() => {}}
+      />
+    );
+  },
+};
diff --git a/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx b/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
index 31134ccfb51..4de80beb0c0 100644
--- a/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
+++ b/packages/graphiql-react/src/components/side-panel/side-panel.stories.tsx
@@ -4,7 +4,14 @@ import { GraphiQLProvider, useGraphiQLActions } from '../provider';
 import { DocsIcon, HistoryIcon } from '../../icons';
 import { SidePanel } from './';
 
-const mockFetcher = () => ({ data: null });
+const mockTransport = {
+  send: async () => ({
+    ok: true,
+    body: { data: null },
+    timing: { totalMs: 0 },
+    size: {},
+  }),
+};
 
 const DOCS_PLUGIN = {
   title: 'Documentation Explorer',
@@ -45,7 +52,7 @@ const meta: Meta<typeof SidePanel> = {
   decorators: [
     Story => (
       <GraphiQLProvider
-        fetcher={mockFetcher}
+        transport={mockTransport}
         plugins={[DOCS_PLUGIN, HISTORY_PLUGIN]}
       >
         <Story />
diff --git a/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx b/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
index 15200eac08c..56e1361ffb2 100644
--- a/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
+++ b/packages/graphiql-react/src/components/top-bar/top-bar.stories.tsx
@@ -2,7 +2,14 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { GraphiQLProvider } from '../provider';
 import { TopBar } from './';
 
-const noOpFetcher = () => Promise.resolve({ data: {} });
+const noOpTransport = {
+  send: async () => ({
+    ok: true,
+    body: { data: {} },
+    timing: { totalMs: 0 },
+    size: {},
+  }),
+};
 
 const meta: Meta<typeof TopBar> = {
   title: 'Layout/TopBar',
@@ -10,7 +17,7 @@ const meta: Meta<typeof TopBar> = {
   tags: ['autodocs'],
   decorators: [
     Story => (
-      <GraphiQLProvider fetcher={noOpFetcher}>
+      <GraphiQLProvider transport={noOpTransport}>
         <Story />
       </GraphiQLProvider>
     ),
diff --git a/packages/graphiql-react/src/constants.ts b/packages/graphiql-react/src/constants.ts
index d4628bc46f6..afc0406d82f 100644
--- a/packages/graphiql-react/src/constants.ts
+++ b/packages/graphiql-react/src/constants.ts
@@ -55,6 +55,7 @@ export const STORAGE_KEY = {
   persistHeaders: 'shouldPersistHeaders',
   theme: 'theme',
   responseView: 'responseView',
+  transportUpgradeBannerDismissed: 'transportUpgradeBannerDismissed',
 } as const;
 
 export const DEFAULT_QUERY = `# Welcome to GraphiQL
diff --git a/packages/graphiql-react/src/index.ts b/packages/graphiql-react/src/index.ts
index e69a1a49ce9..59ab42c0c31 100644
--- a/packages/graphiql-react/src/index.ts
+++ b/packages/graphiql-react/src/index.ts
@@ -25,6 +25,6 @@ export type {
   Theme,
 } from './types';
 export type { GraphiQLPlugin } from './stores/plugin';
-export type { ResponseView, LastResponse } from './stores';
+export type { ResponseView } from './stores';
 export { KEY_MAP, formatShortcutForOS, isMacOs } from './constants';
 export * from './deprecated';
diff --git a/packages/graphiql-react/src/stores/execution.spec.ts b/packages/graphiql-react/src/stores/execution.spec.ts
index fa9b6819780..6940dc5d0ec 100644
--- a/packages/graphiql-react/src/stores/execution.spec.ts
+++ b/packages/graphiql-react/src/stores/execution.spec.ts
@@ -87,3 +87,24 @@ describe('setResponseView', () => {
     expect(storage.get(STORAGE_KEY.responseView)).toBe('json');
   });
 });
+
+describe('dismissTransportUpgradeBanner', () => {
+  it('defaults to not-dismissed', () => {
+    const { store } = makeStore();
+    expect(store.getState().transportUpgradeBannerDismissed).toBe(false);
+  });
+
+  it('flips state to true on call', () => {
+    const { store } = makeStore();
+    store.getState().actions.dismissTransportUpgradeBanner();
+    expect(store.getState().transportUpgradeBannerDismissed).toBe(true);
+  });
+
+  it('persists the dismissal to storage', () => {
+    const { store, storage } = makeStore();
+    store.getState().actions.dismissTransportUpgradeBanner();
+    expect(storage.get(STORAGE_KEY.transportUpgradeBannerDismissed)).toBe(
+      'true',
+    );
+  });
+});
diff --git a/packages/graphiql-react/src/stores/execution.ts b/packages/graphiql-react/src/stores/execution.ts
index 35459a4372b..44509d2c55a 100644
--- a/packages/graphiql-react/src/stores/execution.ts
+++ b/packages/graphiql-react/src/stores/execution.ts
@@ -6,6 +6,8 @@ import {
   GetDefaultFieldNamesFn,
   isAsyncIterable,
   isObservable,
+  Transport,
+  TransportResponse,
   Unsubscribable,
 } from '@graphiql/toolkit';
 import { ExecutionResult, GraphQLError, print } from 'graphql';
@@ -23,21 +25,50 @@ export type ResponseView = 'json' | 'tree' | 'table';
 
 const RESPONSE_VIEWS: readonly ResponseView[] = ['json', 'tree', 'table'];
 
+const byteLength = (value: string): number =>
+  typeof TextEncoder === 'undefined'
+    ? value.length
+    : new TextEncoder().encode(value).length;
+
+/**
+ * Build a `TransportResponse` for the `Fetcher` path, where HTTP status and
+ * headers are unobservable (the contract does not carry them). We populate
+ * what we can measure from the JS side: timing and the formatted-body size.
+ */
+function buildFetcherFallbackResponse(
+  body: ExecutionResult,
+  startMs: number,
+  formattedBody: string,
+): TransportResponse {
+  const errors = (body as { errors?: unknown } | null)?.errors;
+  return {
+    ok: !Array.isArray(errors) || errors.length === 0,
+    body,
+    timing: { totalMs: Date.now() - startMs },
+    size: { response: byteLength(formattedBody) },
+  };
+}
+
+function buildErrorResponse(
+  errorText: string,
+  startMs: number,
+): TransportResponse {
+  return {
+    ok: false,
+    body: {
+      errors: [{ message: errorText }],
+    } as unknown as ExecutionResult,
+    timing: { totalMs: Date.now() - startMs },
+    size: { response: byteLength(errorText) },
+  };
+}
+
 export function isResponseView(value: unknown): value is ResponseView {
   return (
     typeof value === 'string' && RESPONSE_VIEWS.includes(value as ResponseView)
   );
 }
 
-export interface LastResponse {
-  /** HTTP-equivalent status code. 200 for a successful response, 0 if none. */
-  status: number;
-  /** Elapsed time in milliseconds. */
-  timeMs: number;
-  /** Approximate serialized size of the response body in bytes. */
-  sizeBytes: number;
-}
-
 export interface ExecutionSlice {
   /**
    * If there is currently a GraphQL request in-flight. For multipart
@@ -48,11 +79,16 @@ export interface ExecutionSlice {
   isFetching: boolean;
 
   /**
-   * Metadata captured from the most recent completed fetch: status, elapsed
-   * time, and approximate response size. `null` before any request runs.
+   * The full `TransportResponse` envelope from the most recent completed
+   * request. With a `Transport`, this carries the real HTTP wire metadata
+   * (status, headers, timing, size). With a `Fetcher`, only `timing` and
+   * `size.response` can be populated; status/headers are unavailable
+   * because the `Fetcher` contract does not carry them.
+   * `null` before any request runs.
+   *
    * @default null
    */
-  lastResponse: LastResponse | null;
+  lastResponse: TransportResponse | null;
 
   /**
    * Which view is active in the response pane.
@@ -60,6 +96,14 @@ export interface ExecutionSlice {
    */
   responseView: ResponseView;
 
+  /**
+   * Whether the user has dismissed the upgrade-to-`transport` banner in the
+   * response pane. Persisted to storage; honored by the response pane to
+   * decide whether to render any header at all in the `fetcher` path.
+   * @default false
+   */
+  transportUpgradeBannerDismissed: boolean;
+
   /**
    * Represents an active GraphQL subscription.
    *
@@ -95,12 +139,18 @@ export interface ExecutionSlice {
    * `Observable` or `AsyncIterable` that returns the GraphQL response in
    * parsed JSON format.
    *
-   * We suggest using the `createGraphiQLFetcher` utility from `@graphiql/toolkit`
-   * to create these fetcher functions.
-   *
-   * @see {@link https://graphiql-test.netlify.app/typedoc/modules/graphiql_toolkit.html#creategraphiqlfetcher-2|`createGraphiQLFetcher`}
+   * @deprecated Pass a `transport` instead. The `Fetcher` contract cannot
+   * surface HTTP wire metadata (status, headers, timing, size). See
+   * `docs/migration/graphiql-6.0.0.md`.
+   */
+  fetcher?: Fetcher;
+
+  /**
+   * A `Transport` performs the GraphQL request and returns a `TransportResponse`
+   * carrying the parsed body plus the real HTTP wire metadata (status, headers,
+   * timing, size). Mutually exclusive with `fetcher`.
    */
-  fetcher: Fetcher;
+  transport?: Transport;
 }
 
 export interface ExecutionActions {
@@ -118,22 +168,46 @@ export interface ExecutionActions {
    * Change which view is shown in the response pane.
    */
   setResponseView(view: ResponseView): void;
+
+  /**
+   * Mark the upgrade-to-`transport` banner as dismissed and persist the choice.
+   */
+  dismissTransportUpgradeBanner(): void;
 }
 
-export interface ExecutionProps extends Pick<
-  ExecutionSlice,
-  'getDefaultFieldNames' | 'fetcher'
-> {
+type BaseExecutionProps = {
   /**
    * This prop sets the operation name that is passed with a GraphQL request.
    */
   operationName?: string;
-}
+  getDefaultFieldNames?: GetDefaultFieldNamesFn;
+};
+
+/**
+ * Pass exactly one of `fetcher` or `transport`. The two are mutually exclusive
+ * at the type level; passing both is a compile error.
+ *
+ * Prefer `transport`: it lets GraphiQL surface real HTTP wire metadata
+ * (status, headers, timing, size) in the response pane. `fetcher` is
+ * deprecated, but continues to work for existing code.
+ */
+export type ExecutionProps = BaseExecutionProps &
+  (
+    | {
+        /**
+         * @deprecated Use `transport` instead. See
+         * `docs/migration/graphiql-6.0.0.md`.
+         */
+        fetcher: Fetcher;
+        transport?: never;
+      }
+    | { transport: Transport; fetcher?: never }
+  );
 
 type CreateExecutionSlice = (
   initial: Pick<
     ExecutionSlice,
-    'overrideOperationName' | 'getDefaultFieldNames' | 'fetcher'
+    'overrideOperationName' | 'getDefaultFieldNames' | 'fetcher' | 'transport'
   >,
 ) => StateCreator<
   SlicesWithActions,
@@ -218,6 +292,7 @@ export const createExecutionSlice: CreateExecutionSlice =
       isFetching: false,
       lastResponse: null,
       responseView: 'json' as ResponseView,
+      transportUpgradeBannerDismissed: false,
       subscription: null,
       queryId: 0,
       actions: {
@@ -226,6 +301,11 @@ export const createExecutionSlice: CreateExecutionSlice =
           storage.set(STORAGE_KEY.responseView, view);
           set({ responseView: view });
         },
+        dismissTransportUpgradeBanner() {
+          const { storage } = get();
+          storage.set(STORAGE_KEY.transportUpgradeBannerDismissed, 'true');
+          set({ transportUpgradeBannerDismissed: true });
+        },
         stop() {
           set(({ subscription }) => {
             subscription?.unsubscribe();
@@ -246,6 +326,7 @@ export const createExecutionSlice: CreateExecutionSlice =
             overrideOperationName,
             queryId,
             fetcher,
+            transport,
           } = get();
           if (!queryEditor || !responseEditor) {
             return;
@@ -306,7 +387,10 @@ export const createExecutionSlice: CreateExecutionSlice =
           const fetchStartMs = Date.now();
           try {
             const fullResponse: ExecutionResult = {};
-            const handleResponse = (result: ExecutionResult) => {
+            const handleResponse = (
+              result: ExecutionResult,
+              envelope?: TransportResponse,
+            ) => {
               // A different query was dispatched in the meantime, so don't
               // show the results of this one.
               if (newQueryId !== get().queryId) {
@@ -322,94 +406,106 @@ export const createExecutionSlice: CreateExecutionSlice =
                 maybeMultipart = [result];
               }
 
+              let formattedBody: string;
+              let mergedBody: ExecutionResult;
               if (maybeMultipart) {
                 for (const part of maybeMultipart) {
                   mergeIncrementalResult(fullResponse, part);
                 }
-
-                const formatted = formatResult(fullResponse);
-                set({
-                  isFetching: false,
-                  lastResponse: {
-                    status: fullResponse.errors?.length ? 200 : 200,
-                    timeMs: Date.now() - fetchStartMs,
-                    sizeBytes: new TextEncoder().encode(formatted).length,
-                  },
-                });
-                setResponse(formatted);
+                mergedBody = fullResponse;
+                formattedBody = formatResult(fullResponse);
               } else {
-                const formatted = formatResult(result);
-                const hasErrors =
-                  typeof result === 'object' &&
-                  result !== null &&
-                  'errors' in result &&
-                  Array.isArray((result as ExecutionResult).errors) &&
-                  (result as ExecutionResult).errors!.length > 0;
-                set({
-                  isFetching: false,
-                  lastResponse: {
-                    status: hasErrors ? 200 : 200,
-                    timeMs: Date.now() - fetchStartMs,
-                    sizeBytes: new TextEncoder().encode(formatted).length,
-                  },
-                });
-                setResponse(formatted);
+                mergedBody = result;
+                formattedBody = formatResult(result);
               }
+
+              set({
+                isFetching: false,
+                lastResponse:
+                  envelope ??
+                  buildFetcherFallbackResponse(
+                    mergedBody,
+                    fetchStartMs,
+                    formattedBody,
+                  ),
+              });
+              setResponse(formattedBody);
             };
             const opName = overrideOperationName ?? operationName;
-            const fetch = fetcher(
-              { query, variables, operationName: opName },
-              { headers, documentAST },
-            );
-
-            const value = await fetch;
-            if (isObservable(value)) {
-              // If the fetcher returned an Observable, then subscribe to it, calling
-              // the callback on each next value and handling both errors and the
-              // completion of the Observable.
-              const newSubscription = value.subscribe({
-                next(result) {
-                  handleResponse(result);
-                },
-                error(error: Error) {
-                  const errorText = formatError(error);
-                  set({
-                    isFetching: false,
-                    lastResponse: {
-                      status: 0,
-                      timeMs: Date.now() - fetchStartMs,
-                      sizeBytes: new TextEncoder().encode(errorText).length,
-                    },
-                    subscription: null,
-                  });
-                  setResponse(errorText);
-                },
-                complete() {
-                  set({ isFetching: false, subscription: null });
-                },
+
+            if (transport) {
+              const result = transport.send({
+                query,
+                variables,
+                operationName: opName,
+                headers: headers as Record<string, string> | undefined,
               });
-              set({ subscription: newSubscription });
-            } else if (isAsyncIterable(value)) {
-              const newSubscription = {
-                unsubscribe: () => value[Symbol.asyncIterator]().return?.(),
-              };
-              set({ subscription: newSubscription });
-              for await (const result of value) {
-                handleResponse(result);
+
+              if (isAsyncIterable(result)) {
+                const iter = result as AsyncIterable<TransportResponse>;
+                const newSubscription = {
+                  unsubscribe: () => iter[Symbol.asyncIterator]().return?.(),
+                };
+                set({ subscription: newSubscription });
+                for await (const tr of iter) {
+                  handleResponse(tr.body as ExecutionResult, tr);
+                }
+                set({ isFetching: false, subscription: null });
+              } else {
+                const tr = await result;
+                handleResponse(tr.body as ExecutionResult, tr);
+              }
+            } else if (fetcher) {
+              const fetch = fetcher(
+                { query, variables, operationName: opName },
+                { headers, documentAST },
+              );
+
+              const value = await fetch;
+              if (isObservable(value)) {
+                // If the fetcher returned an Observable, then subscribe to it, calling
+                // the callback on each next value and handling both errors and the
+                // completion of the Observable.
+                const newSubscription = value.subscribe({
+                  next(result) {
+                    handleResponse(result);
+                  },
+                  error(error: Error) {
+                    const errorText = formatError(error);
+                    set({
+                      isFetching: false,
+                      lastResponse: buildErrorResponse(errorText, fetchStartMs),
+                      subscription: null,
+                    });
+                    setResponse(errorText);
+                  },
+                  complete() {
+                    set({ isFetching: false, subscription: null });
+                  },
+                });
+                set({ subscription: newSubscription });
+              } else if (isAsyncIterable(value)) {
+                const newSubscription = {
+                  unsubscribe: () => value[Symbol.asyncIterator]().return?.(),
+                };
+                set({ subscription: newSubscription });
+                for await (const result of value) {
+                  handleResponse(result);
+                }
+                set({ isFetching: false, subscription: null });
+              } else {
+                handleResponse(value);
               }
-              set({ isFetching: false, subscription: null });
             } else {
-              handleResponse(value);
+              throw new Error(
+                'No fetcher or transport configured on `GraphiQLProvider`.',
+              );
             }
           } catch (error) {
             const errorText = formatError(error);
             set({
               isFetching: false,
-              lastResponse: {
-                status: 0,
-                timeMs: Date.now() - fetchStartMs,
-                sizeBytes: new TextEncoder().encode(errorText).length,
-              },
+              lastResponse: buildErrorResponse(errorText, fetchStartMs),
               subscription: null,
             });
             setResponse(errorText);
diff --git a/packages/graphiql-react/src/stores/index.ts b/packages/graphiql-react/src/stores/index.ts
index 08e127372ee..5221cc66d1f 100644
--- a/packages/graphiql-react/src/stores/index.ts
+++ b/packages/graphiql-react/src/stores/index.ts
@@ -11,7 +11,6 @@ export {
   type ExecutionActions,
   type ExecutionProps,
   type ResponseView,
-  type LastResponse,
 } from './execution';
 export {
   createPluginSlice,
diff --git a/packages/graphiql-react/src/stores/schema.ts b/packages/graphiql-react/src/stores/schema.ts
index b11947f0fb5..e1cdbb3c64a 100644
--- a/packages/graphiql-react/src/stores/schema.ts
+++ b/packages/graphiql-react/src/stores/schema.ts
@@ -3,7 +3,9 @@ import {
   fetcherReturnToPromise,
   formatError,
   formatResult,
+  isAsyncIterable,
   isPromise,
+  type Fetcher,
 } from '@graphiql/toolkit';
 import {
   buildClientSchema,
@@ -60,6 +62,7 @@ export const createSchemaSlice: CreateSchemaSlice = initial => (set, get) => ({
         onSchemaChange,
         headerEditor,
         fetcher,
+        transport,
         inputValueDeprecation,
         introspectionQueryName,
         schemaDescription,
@@ -94,9 +97,39 @@ export const createSchemaSlice: CreateSchemaSlice = initial => (set, get) => ({
           schemaDescription,
         });
 
+        // When the consumer passed a `transport`, project it into a Fetcher-shaped
+        // adapter just for introspection: take the first yielded `TransportResponse`
+        // and return its `body` (the `ExecutionResult`).
+        const introspectionFetcher: Fetcher = transport
+          ? ((async params => {
+              const sendResult = transport.send({
+                query: params.query,
+                operationName: params.operationName,
+                variables: params.variables,
+                headers: headers as Record<string, string> | undefined,
+              });
+              let body: unknown;
+              if (isAsyncIterable(sendResult)) {
+                const iter = sendResult[Symbol.asyncIterator]();
+                const first = await iter.next();
+                await iter.return?.();
+                if (first.done || !first.value) {
+                  throw new Error(
+                    'Empty introspection response from transport.',
+                  );
+                }
+                body = first.value.body;
+              } else {
+                body = (await sendResult).body;
+              }
+              const result = Array.isArray(body) ? body[0] : body;
+              return result as Awaited<ReturnType<Fetcher>>;
+            }) as Fetcher)
+          : fetcher!;
+
         function doIntrospection(query: string) {
           const fetch = fetcherReturnToPromise(
-            fetcher(
+            introspectionFetcher(
               { query, operationName: introspectionQueryName },
               fetcherOpts,
             ),
diff --git a/packages/graphiql-toolkit/docs/create-fetcher.md b/packages/graphiql-toolkit/docs/create-fetcher.md
index 939f6e9f872..c6d58dc6bff 100644
--- a/packages/graphiql-toolkit/docs/create-fetcher.md
+++ b/packages/graphiql-toolkit/docs/create-fetcher.md
@@ -1,3 +1,7 @@
+> [!WARNING]
+> `createGraphiQLFetcher` is deprecated. Use [`createTransport`](./create-transport.md) instead.
+> See the [GraphiQL 6 migration guide](../../docs/migration/graphiql-6.0.0.md) for upgrade instructions.
+
 # `createGraphiQLFetcher`
 
 A utility for generating a full-featured `fetcher` for GraphiQL including
diff --git a/packages/graphiql-toolkit/src/create-fetcher/createFetcher.ts b/packages/graphiql-toolkit/src/create-fetcher/createFetcher.ts
index b90c65ee83e..6d8e90cd437 100644
--- a/packages/graphiql-toolkit/src/create-fetcher/createFetcher.ts
+++ b/packages/graphiql-toolkit/src/create-fetcher/createFetcher.ts
@@ -11,6 +11,10 @@ import {
  * build a GraphiQL fetcher that is:
  * - backwards compatible
  * - optionally supports graphql-ws or `
+ *
+ * @deprecated Use `createTransport` from `@graphiql/toolkit` instead. The new
+ * API surfaces real response metadata (status, headers, timing, size) that the
+ * `Fetcher` contract cannot expose. See `docs/migration/graphiql-6.0.0.md`.
  */
 export function createGraphiQLFetcher(options: CreateFetcherOptions): Fetcher {
   const httpFetch =
diff --git a/packages/graphiql-toolkit/src/create-fetcher/lib.ts b/packages/graphiql-toolkit/src/create-fetcher/lib.ts
index 6f046d8f41b..9dd0d4f6566 100644
--- a/packages/graphiql-toolkit/src/create-fetcher/lib.ts
+++ b/packages/graphiql-toolkit/src/create-fetcher/lib.ts
@@ -19,11 +19,64 @@ import type {
   ExecutionResultPayload,
   CreateFetcherOptions,
 } from './types';
+// Type-only import: erased at build time, so no runtime dependency cycle with
+// `create-transport`, which imports the helpers below at runtime.
+import type { TransportResponse } from '../create-transport/types';
 
 const errorHasCode = (err: unknown): err is { code: string } => {
   return typeof err === 'object' && err !== null && 'code' in err;
 };
 
+const byteLength = (value: string): number =>
+  typeof TextEncoder === 'undefined'
+    ? value.length
+    : new TextEncoder().encode(value).length;
+
+const headersToObject = (
+  headers: unknown,
+): Record<string, string> | undefined => {
+  const headersLike = headers as
+    | { forEach?: (cb: (value: string, key: string) => void) => void }
+    | undefined;
+  if (!headersLike || typeof headersLike.forEach !== 'function') {
+    return undefined;
+  }
+  const result: Record<string, string> = {};
+  headersLike.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+};
+
+/**
+ * Build a `TransportResponse` from a parsed body and the HTTP `Response` it came
+ * from. This is the single place wire metadata is read off the response, so the
+ * `Fetcher` projection and `createTransport` observe identical data.
+ */
+function toTransportResponse(
+  body: unknown,
+  response: Response,
+  startMs: number,
+  requestBody?: string,
+): TransportResponse {
+  const errors = (body as { errors?: unknown } | null)?.errors;
+  const contentLength = response.headers?.get?.('content-length');
+  return {
+    ok: !Array.isArray(errors) || errors.length === 0,
+    status: response.status,
+    statusText: response.statusText,
+    headers: headersToObject(response.headers),
+    body: body as TransportResponse['body'],
+    timing: { totalMs: performance.now() - startMs },
+    size: {
+      request: requestBody === undefined ? undefined : byteLength(requestBody),
+      response: contentLength
+        ? Number(contentLength)
+        : byteLength(JSON.stringify(body)),
+    },
+  };
+}
+
 /**
  * Returns true if the name matches a subscription in the AST
  *
@@ -46,6 +99,34 @@ export const isSubscriptionWithName = (
   return isSubscription;
 };
 
+/**
+ * Perform a simple HTTP/S request and return the full `TransportResponse`
+ * (parsed body plus wire metadata). This is the primitive that
+ * `createSimpleFetcher` projects down to the body, and that `createTransport`
+ * exposes whole.
+ */
+export const simpleHttpTransport =
+  (options: CreateFetcherOptions, httpFetch: typeof fetch) =>
+  async (
+    graphQLParams: FetcherParams,
+    fetcherOpts?: FetcherOpts,
+  ): Promise<TransportResponse> => {
+    const startMs = performance.now();
+    const requestBody = JSON.stringify(graphQLParams);
+    const response = await httpFetch(options.url, {
+      method: 'POST',
+      body: requestBody,
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/graphql-response+json, application/json;q=0.9',
+        ...options.headers,
+        ...fetcherOpts?.headers,
+      },
+    });
+    const body = await response.json();
+    return toTransportResponse(body, response, startMs, requestBody);
+  };
+
 /**
  * create a simple HTTP/S fetcher using a fetch implementation where
  * multipart is not needed
@@ -133,6 +214,66 @@ export const createLegacyWebsocketsFetcher =
       sink => observable.subscribe(sink).unsubscribe,
     );
   };
+/**
+ * Perform an `IncrementalDelivery` (`multipart/mixed`) request for `@stream` /
+ * `@defer`, yielding a `TransportResponse` per chunk. HTTP metadata is read once
+ * from the raw response and attached to every chunk (they share one response).
+ */
+export const multipartHttpTransport = (
+  options: CreateFetcherOptions,
+  httpFetch: typeof fetch,
+) =>
+  async function* (
+    graphQLParams: FetcherParams,
+    fetcherOpts?: FetcherOpts,
+  ): AsyncGenerator<TransportResponse> {
+    const startMs = performance.now();
+    const requestBody = JSON.stringify(graphQLParams);
+    const rawResponse = await httpFetch(options.url, {
+      method: 'POST',
+      body: requestBody,
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, multipart/mixed',
+        ...options.headers,
+        // allow user-defined headers to override
+        // the static provided headers
+        ...fetcherOpts?.headers,
+      },
+    });
+    const response = await meros<
+      Extract<ExecutionResultPayload, { hasNext: boolean }>
+    >(rawResponse, { multiple: true });
+
+    // Single, non-multipart response: behaves like the simple transport.
+    if (!isAsyncIterable(response)) {
+      yield toTransportResponse(
+        await response.json(),
+        rawResponse,
+        startMs,
+        requestBody,
+      );
+      return;
+    }
+
+    for await (const chunk of response) {
+      if (chunk.some(part => !part.json)) {
+        const message = chunk.map(
+          part => `Headers::\n${part.headers}\n\nBody::\n${part.body}`,
+        );
+        throw new Error(
+          `Expected multipart chunks to be of json type. got:\n${message}`,
+        );
+      }
+      yield toTransportResponse(
+        chunk.map(part => part.body) as TransportResponse['body'],
+        rawResponse,
+        startMs,
+        requestBody,
+      );
+    }
+  };
+
 /**
  * Create a fetcher with the `IncrementalDelivery` HTTP/S spec for
  * `@stream` and `@defer` support using `fetch-multipart-graphql`
diff --git a/packages/graphiql-toolkit/src/create-fetcher/types.ts b/packages/graphiql-toolkit/src/create-fetcher/types.ts
index 7d3a9dac011..3a6200cfc3e 100644
--- a/packages/graphiql-toolkit/src/create-fetcher/types.ts
+++ b/packages/graphiql-toolkit/src/create-fetcher/types.ts
@@ -24,12 +24,20 @@ export type Unsubscribable = {
   unsubscribe: () => void;
 };
 
+/**
+ * @deprecated Use the `Transport` API and `TransportRequest` from `@graphiql/toolkit`
+ * instead. See `docs/migration/graphiql-6.0.0.md`.
+ */
 export type FetcherParams = {
   query: string;
   operationName?: string | null;
   variables?: any;
 };
 
+/**
+ * @deprecated Use the `Transport` API from `@graphiql/toolkit` instead.
+ * See `docs/migration/graphiql-6.0.0.md`.
+ */
 export type FetcherOpts = {
   headers?: { [key: string]: any };
   documentAST?: DocumentNode;
@@ -67,6 +75,12 @@ export type SyncFetcherResult = SyncExecutionResult;
 
 export type FetcherReturnType = MaybePromise<SyncExecutionResult>;
 
+/**
+ * @deprecated Use `Transport` from `@graphiql/toolkit` instead. A `Transport` is
+ * an object with a `send(request)` method that returns a `TransportResponse`
+ * carrying the real HTTP wire data (status, headers, timing, size).
+ * See `docs/migration/graphiql-6.0.0.md`.
+ */
 export type Fetcher = (
   graphQLParams: FetcherParams,
   opts?: FetcherOpts,
@@ -74,6 +88,9 @@ export type Fetcher = (
 
 /**
  * Options for creating a simple, spec-compliant GraphiQL fetcher
+ *
+ * @deprecated Use `CreateTransportOptions` from `@graphiql/toolkit` instead.
+ * See `docs/migration/graphiql-6.0.0.md`.
  */
 export interface CreateFetcherOptions {
   /**
diff --git a/packages/graphiql-toolkit/src/create-transport/__tests__/createTransport.spec.ts b/packages/graphiql-toolkit/src/create-transport/__tests__/createTransport.spec.ts
new file mode 100644
index 00000000000..2240d142c93
--- /dev/null
+++ b/packages/graphiql-toolkit/src/create-transport/__tests__/createTransport.spec.ts
@@ -0,0 +1,173 @@
+import { type Mock, describe, it, expect, vi, afterEach } from 'vitest';
+import 'isomorphic-fetch';
+
+import { createTransport } from '../createTransport';
+import {
+  createSimpleFetcher,
+  createWebsocketsFetcherFromClient,
+} from '../../create-fetcher/lib';
+import type { Client } from 'graphql-ws';
+import type { TransportResponse } from '../types';
+
+// Keep the real HTTP transport helpers; only stub the client-to-fetcher adapter
+// so no real socket is required.
+vi.mock('../../create-fetcher/lib', async () => {
+  const actual = await vi.importActual('../../create-fetcher/lib');
+  return {
+    ...actual,
+    createWebsocketsFetcherFromClient: vi.fn(),
+  };
+});
+
+const URL = 'http://localhost:3000/graphql';
+const QUERY = '{ __typename }';
+const SUBSCRIPTION = 'subscription OnTick { tick }';
+
+function mockResponse(
+  body: unknown,
+  init: { status?: number; statusText?: string; headers?: HeadersInit } = {},
+) {
+  return {
+    status: init.status ?? 200,
+    statusText: init.statusText ?? 'OK',
+    headers: new Headers(
+      init.headers ?? { 'content-type': 'application/json' },
+    ),
+    json: () => Promise.resolve(body),
+  };
+}
+
+function mockFetchWith(
+  body: unknown,
+  init?: { status?: number; statusText?: string; headers?: HeadersInit },
+): typeof fetch {
+  return vi
+    .fn()
+    .mockResolvedValue(mockResponse(body, init)) as unknown as typeof fetch;
+}
+
+describe('createTransport — query / mutation', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('resolves a Promise<TransportResponse> with real wire metadata', async () => {
+    const transport = createTransport({
+      url: URL,
+      enableIncrementalDelivery: false,
+      fetch: mockFetchWith(
+        { data: { __typename: 'Query' } },
+        { status: 200, statusText: 'OK' },
+      ),
+    });
+
+    const result = transport.send({ query: QUERY });
+    expect(result).toBeInstanceOf(Promise);
+
+    const response = (await result) as TransportResponse;
+    expect(response).toMatchObject({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      body: { data: { __typename: 'Query' } },
+    });
+    expect(response.headers?.['content-type']).toBe('application/json');
+    expect(response.timing.totalMs).toBeGreaterThanOrEqual(0);
+    expect(response.size.request).toBeGreaterThan(0);
+    expect(response.size.response).toBeGreaterThan(0);
+  });
+
+  it('prefers the content-length header for response size when present', async () => {
+    const transport = createTransport({
+      url: URL,
+      enableIncrementalDelivery: false,
+      fetch: mockFetchWith(
+        { data: {} },
+        {
+          headers: {
+            'content-type': 'application/json',
+            'content-length': '42',
+          },
+        },
+      ),
+    });
+    const response = (await transport.send({
+      query: QUERY,
+    })) as TransportResponse;
+    expect(response.size.response).toBe(42);
+  });
+
+  it('sets ok=false when the response body contains errors', async () => {
+    const transport = createTransport({
+      url: URL,
+      enableIncrementalDelivery: false,
+      fetch: mockFetchWith({ data: null, errors: [{ message: 'boom' }] }),
+    });
+    const response = (await transport.send({
+      query: QUERY,
+    })) as TransportResponse;
+    expect(response.ok).toBe(false);
+  });
+});
+
+describe('createTransport — subscription', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns an AsyncIterable<TransportResponse> with no HTTP envelope', async () => {
+    (createWebsocketsFetcherFromClient as Mock).mockReturnValue(() =>
+      (async function* () {
+        yield { data: { tick: 1 } };
+        yield { data: { tick: 2 } };
+      })(),
+    );
+
+    const transport = createTransport({
+      url: URL,
+      // Truthy placeholder; the real client never gets called since the
+      // adapter above is mocked.
+      subscriptionClient: {} as Client,
+    });
+    const result = transport.send({ query: SUBSCRIPTION });
+
+    expect(
+      result !== null &&
+        typeof result === 'object' &&
+        Symbol.asyncIterator in result,
+    ).toBe(true);
+
+    const events: TransportResponse[] = [];
+    for await (const event of result as AsyncIterable<TransportResponse>) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({ ok: true, body: { data: { tick: 1 } } });
+    // No HTTP response envelope for a socket.
+    expect(events[0].status).toBeUndefined();
+    expect(events[0].headers).toBeUndefined();
+    expect(events[0].size.response).toBeGreaterThan(0);
+  });
+
+  it('throws when no subscriptionClient is provided', async () => {
+    const transport = createTransport({ url: URL });
+    const result = transport.send({ query: SUBSCRIPTION });
+    await expect(async () => {
+      for await (const _ of result as AsyncIterable<TransportResponse>) {
+        // drain
+      }
+    }).rejects.toThrow(/not configured for subscriptions/);
+  });
+});
+
+describe('createSimpleFetcher (backward-compatible)', () => {
+  it('returns the parsed body, unaffected by the new Transport API', async () => {
+    const fetcher = createSimpleFetcher(
+      { url: URL },
+      mockFetchWith({ data: { __typename: 'Query' } }),
+    );
+    const result = await fetcher({ query: QUERY }, {});
+    expect(result).toEqual({ data: { __typename: 'Query' } });
+  });
+});
diff --git a/packages/graphiql-toolkit/src/create-transport/createTransport.ts b/packages/graphiql-toolkit/src/create-transport/createTransport.ts
new file mode 100644
index 00000000000..918149a637b
--- /dev/null
+++ b/packages/graphiql-toolkit/src/create-transport/createTransport.ts
@@ -0,0 +1,128 @@
+import { parse } from 'graphql';
+import type { OperationDefinitionNode } from 'graphql';
+import type { Client } from 'graphql-ws';
+import {
+  createWebsocketsFetcherFromClient,
+  multipartHttpTransport,
+  simpleHttpTransport,
+} from '../create-fetcher/lib';
+import type {
+  CreateFetcherOptions,
+  FetcherParams,
+} from '../create-fetcher/types';
+import type {
+  CreateTransportOptions,
+  Transport,
+  TransportRequest,
+  TransportResponse,
+} from './types';
+
+function selectedOperationIsSubscription(
+  query: string,
+  operationName?: string | null,
+): boolean {
+  let document;
+  try {
+    document = parse(query);
+  } catch {
+    return false;
+  }
+  const operations = document.definitions.filter(
+    (def): def is OperationDefinitionNode => def.kind === 'OperationDefinition',
+  );
+  const operation = operationName
+    ? operations.find(op => op.name?.value === operationName)
+    : operations.length === 1
+      ? operations[0]
+      : undefined;
+  return operation?.operation === 'subscription';
+}
+
+const byteLength = (value: string): number =>
+  typeof TextEncoder === 'undefined'
+    ? value.length
+    : new TextEncoder().encode(value).length;
+
+/**
+ * Wrap one subscription event. A socket has no HTTP response, so `status`,
+ * `statusText` and `headers` are intentionally absent.
+ */
+function toSubscriptionResponse(
+  event: unknown,
+  startMs: number,
+): TransportResponse {
+  const errors = (event as { errors?: unknown } | null)?.errors;
+  return {
+    ok: !Array.isArray(errors) || errors.length === 0,
+    body: event as TransportResponse['body'],
+    timing: { totalMs: performance.now() - startMs },
+    size: { response: byteLength(JSON.stringify(event)) },
+  };
+}
+
+/**
+ * Create a `Transport`: the wire-level primitive that owns the request and
+ * surfaces structured response metadata.
+ *
+ * - Queries / mutations: `send()` returns `Promise<TransportResponse>` when
+ *   incremental delivery is off, or an `AsyncIterable<TransportResponse>`
+ *   (one chunk per payload) when it is on.
+ * - Subscriptions: `send()` returns an `AsyncIterable<TransportResponse>`,
+ *   one event at a time. A `subscriptionClient` must be configured; the
+ *   toolkit does not construct one for you.
+ */
+export function createTransport(opts: CreateTransportOptions): Transport {
+  const httpFetch =
+    opts.fetch || (typeof window !== 'undefined' && window.fetch);
+  if (!httpFetch) {
+    throw new Error('No valid fetch implementation available');
+  }
+
+  const incrementalDelivery = opts.enableIncrementalDelivery !== false;
+
+  const fetcherOptions: CreateFetcherOptions = {
+    url: opts.url,
+    headers: opts.headers,
+  };
+
+  const simple = simpleHttpTransport(fetcherOptions, httpFetch);
+  const multipart = multipartHttpTransport(fetcherOptions, httpFetch);
+
+  function send(
+    req: TransportRequest,
+  ): Promise<TransportResponse> | AsyncIterable<TransportResponse> {
+    const params: FetcherParams = {
+      query: req.query,
+      operationName: req.operationName ?? undefined,
+      variables: req.variables,
+    };
+    const fetcherOpts = req.headers ? { headers: req.headers } : undefined;
+
+    if (selectedOperationIsSubscription(req.query, req.operationName)) {
+      return subscribe(opts.subscriptionClient, params);
+    }
+    if (incrementalDelivery) {
+      return multipart(params, fetcherOpts);
+    }
+    return simple(params, fetcherOpts);
+  }
+
+  return { send };
+}
+
+async function* subscribe(
+  subscriptionClient: Client | undefined,
+  params: FetcherParams,
+): AsyncGenerator<TransportResponse> {
+  if (!subscriptionClient) {
+    throw new Error(
+      "createTransport is not configured for subscriptions. Pass a `subscriptionClient` (e.g. `graphql-ws`'s `createClient({ url })` or `graphql-sse`'s `createClient({ url })`). See docs/migration/graphiql-6.0.0.md.",
+    );
+  }
+  const wsFetcher = createWebsocketsFetcherFromClient(subscriptionClient);
+  const iterable = wsFetcher(params) as AsyncIterable<unknown>;
+  const startMs = performance.now();
+  for await (const event of iterable) {
+    yield toSubscriptionResponse(event, startMs);
+  }
+}
diff --git a/packages/graphiql-toolkit/src/create-transport/index.ts b/packages/graphiql-toolkit/src/create-transport/index.ts
new file mode 100644
index 00000000000..f169898c2c6
--- /dev/null
+++ b/packages/graphiql-toolkit/src/create-transport/index.ts
@@ -0,0 +1,2 @@
+export * from './types';
+export { createTransport } from './createTransport';
diff --git a/packages/graphiql-toolkit/src/create-transport/types.ts b/packages/graphiql-toolkit/src/create-transport/types.ts
new file mode 100644
index 00000000000..5aa09a96650
--- /dev/null
+++ b/packages/graphiql-toolkit/src/create-transport/types.ts
@@ -0,0 +1,92 @@
+import type { ExecutionResult } from 'graphql';
+import type { Client } from 'graphql-ws';
+
+export type TransportRequest = {
+  query: string;
+  operationName?: string | null;
+  variables?: Record<string, unknown>;
+  /**
+   * Per-request headers, merged with (and overriding) the static headers passed
+   * to `createTransport`.
+   */
+  headers?: Record<string, string>;
+};
+
+/**
+ * Per-resolver trace, if the server returns timing data (e.g. Apollo tracing).
+ * Not populated yet; reserved so the response shape is stable for a later
+ * trace-extension parser.
+ */
+export type ResolverTrace = {
+  path: (string | number)[];
+  parentType: string;
+  fieldName: string;
+  returnType: string;
+  startOffsetMs: number;
+  durationMs: number;
+};
+
+/**
+ * A single execution result plus the wire-level metadata around it.
+ *
+ * `status`, `statusText` and `headers` are optional because not every
+ * transport has an HTTP response envelope: a WebSocket subscription emits
+ * results over a socket, and a user-supplied fetcher only ever returns the
+ * parsed result. Absent fields mean "this transport can't observe it", which
+ * is honest, rather than a fabricated `200`.
+ */
+export type TransportResponse = {
+  ok: boolean;
+  status?: number;
+  statusText?: string;
+  headers?: Record<string, string>;
+  /**
+   * A single execution result, or an array of incremental payloads for one
+   * `multipart/mixed` chunk (`@defer`/`@stream`).
+   */
+  body: ExecutionResult | ExecutionResult[];
+  timing: { totalMs: number; resolverTraces?: ResolverTrace[] };
+  size: { request?: number; response?: number };
+};
+
+/**
+ * Wire-level transport. `send()` returns a single Promise for queries and
+ * mutations, or an AsyncIterable for subscriptions and incremental delivery
+ * (each event/chunk is wrapped in its own `TransportResponse`).
+ */
+export type Transport = {
+  send(
+    request: TransportRequest,
+  ): Promise<TransportResponse> | AsyncIterable<TransportResponse>;
+};
+
+export type CreateTransportOptions = {
+  /**
+   * URL for HTTP(S) requests. Required.
+   */
+  url: string;
+  /**
+   * Static request headers, merged with (and overridable by) per-request headers.
+   */
+  headers?: Record<string, string>;
+  /**
+   * A pre-built subscription client whose `.subscribe(payload, sink)` matches
+   * the `graphql-ws` `Client` shape. `graphql-sse`'s `createClient()` is
+   * signature-compatible, so SSE subscriptions work without any SSE-specific
+   * code in the toolkit.
+   *
+   * Construct the client yourself and pass it in; the toolkit does not build
+   * one for you. If a subscription is sent without this option configured,
+   * `send()` throws.
+   */
+  subscriptionClient?: Client;
+  /**
+   * Use `multipart/mixed` incremental delivery for `@defer`/`@stream`.
+   * Defaults to true.
+   */
+  enableIncrementalDelivery?: boolean;
+  /**
+   * Custom fetch implementation. Defaults to the global fetch.
+   */
+  fetch?: typeof fetch;
+};
diff --git a/packages/graphiql-toolkit/src/index.ts b/packages/graphiql-toolkit/src/index.ts
index 503f6fcf711..42b8d1012d5 100644
--- a/packages/graphiql-toolkit/src/index.ts
+++ b/packages/graphiql-toolkit/src/index.ts
@@ -1,5 +1,6 @@
 export * from './async-helpers';
 export * from './create-fetcher';
+export * from './create-transport';
 export * from './format';
 export * from './graphql-helpers';
 export * from './storage';
diff --git a/packages/graphiql/README.md b/packages/graphiql/README.md
index 24b3526a587..cedc564d095 100644
--- a/packages/graphiql/README.md
+++ b/packages/graphiql/README.md
@@ -92,29 +92,29 @@ The package exports a bunch of React components:
 - The `GraphiQL` component is a combination of both the above components
 
 There is a single prop that is required for the `GraphiQL` component called
-fetcher. A fetcher is a function that performs a request to a GraphQL API. It
-may return a `Promise` for queries or mutations, but also an `Observable` or an
-`AsyncIterable` in order to handle subscriptions or multipart responses.
+`transport`. A transport is a function that performs a request to a GraphQL API.
+It may return a `Promise` for queries or mutations, but also an `Observable` or
+an `AsyncIterable` in order to handle subscriptions or multipart responses.
 
-An easy way to get create such a function is the
-[`createGraphiQLFetcher`](../graphiql-toolkit/src/create-fetcher/createFetcher.ts)
+An easy way to create such a function is the
+[`createTransport`](../graphiql-toolkit/src/create-fetcher/createFetcher.ts)
 method exported from the `@graphiql/toolkit` package. If you want to implement
-your own fetcher function, you can use the `Fetcher` type from
+your own transport function, you can use the `Transport` type from
 `@graphiql/toolkit` to make sure the signature matches what GraphiQL expects.
 
 The following is everything you need to render GraphiQL in your React
 application:
 
 ```jsx
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 import { GraphiQL } from 'graphiql';
 import { createRoot } from 'react-dom/client';
 import 'graphiql/style.css';
 
-const fetcher = createGraphiQLFetcher({ url: 'https://my.backend/graphql' });
+const transport = createTransport({ url: 'https://my.backend/graphql' });
 
 const root = createRoot(document.getElementById('root'));
-root.render(<GraphiQL fetcher={fetcher} />);
+root.render(<GraphiQL transport={transport} />);
 ```
 
 ## Customize
@@ -215,9 +215,9 @@ namespace, isolating each instance’s state and avoiding collisions.
 ```tsx
 import type { FC } from 'react';
 import { GraphiQL } from 'graphiql';
-import { createGraphiQLFetcher } from '@graphiql/toolkit';
+import { createTransport } from '@graphiql/toolkit';
 
-const fetcher = createGraphiQLFetcher({ url: 'https://my.backend/graphql' });
+const transport = createTransport({ url: 'https://my.backend/graphql' });
 
 const NAMESPACE = 'my-namespace';
 
@@ -235,6 +235,6 @@ const storage: typeof localStorage = {
 };
 
 export const App: FC = () => {
-  return <GraphiQL fetcher={fetcher} storage={myStorage} />;
+  return <GraphiQL transport={transport} storage={myStorage} />;
 };
 ```
diff --git a/packages/graphiql/cypress/e2e/transport.cy.ts b/packages/graphiql/cypress/e2e/transport.cy.ts
new file mode 100644
index 00000000000..b526630458c
--- /dev/null
+++ b/packages/graphiql/cypress/e2e/transport.cy.ts
@@ -0,0 +1,59 @@
+/**
+ * The CDN demo in `packages/graphiql/src/e2e.ts` uses `createTransport` and the
+ * `<GraphiQL transport={...}>` prop. These tests confirm that the response pane
+ * header shows real wire metadata from the actual HTTP response (status code,
+ * timing, response size) and that the upgrade banner is NOT shown because
+ * `transport` is in use, not `fetcher`.
+ */
+
+const testQuery = `{
+  longDescriptionType {
+    id
+  }
+}`;
+
+describe('Transport API + response pane header', () => {
+  it('Shows the real HTTP status code badge after a successful query', () => {
+    cy.visitWithOp({ query: testQuery });
+    cy.clickExecuteQuery();
+    cy.get('.graphiql-response-status-code').should('contain.text', '200');
+    cy.get('.graphiql-response-status').should(
+      'have.class',
+      'graphiql-response-status--ok',
+    );
+  });
+
+  it('Shows a real timing badge in ms', () => {
+    cy.visitWithOp({ query: testQuery });
+    cy.clickExecuteQuery();
+    cy.get('.graphiql-response-meta')
+      .first()
+      .invoke('text')
+      .should('match', /^\d+ms$/);
+  });
+
+  it('Shows a non-zero response size badge', () => {
+    cy.visitWithOp({ query: testQuery });
+    cy.clickExecuteQuery();
+    // size badge is rendered as e.g. "123 B" or "1.2 KB"
+    cy.get('.graphiql-response-meta')
+      .last()
+      .invoke('text')
+      .should('match', /^(\d+\s?B|\d+(?:\.\d+)?\s?KB|\d+(?:\.\d+)?\s?MB)$/);
+  });
+
+  it('Surfaces an error status when the response is a 500', () => {
+    cy.intercept('/graphql', { statusCode: 500, body: { errors: [] } });
+    cy.visitWithOp({ query: testQuery });
+    cy.clickExecuteQuery();
+    cy.get('.graphiql-response-status').should(
+      'have.class',
+      'graphiql-response-status--error',
+    );
+  });
+
+  it('Does NOT show the upgrade banner when a `transport` is configured', () => {
+    cy.visit('/');
+    cy.get('.graphiql-transport-upgrade-banner').should('not.exist');
+  });
+});
diff --git a/packages/graphiql/package.json b/packages/graphiql/package.json
index 175f907e55d..b500bab639e 100644
--- a/packages/graphiql/package.json
+++ b/packages/graphiql/package.json
@@ -75,6 +75,7 @@
     "cypress": "^13.13.2",
     "cypress-axe": "^1",
     "graphql": "^16.11.0",
+    "graphql-ws": "^5.5.5",
     "lightningcss": "^1.29.3",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
diff --git a/packages/graphiql/src/GraphiQL.spec.tsx b/packages/graphiql/src/GraphiQL.spec.tsx
index c393dfa3f14..66093bc6f9d 100644
--- a/packages/graphiql/src/GraphiQL.spec.tsx
+++ b/packages/graphiql/src/GraphiQL.spec.tsx
@@ -11,7 +11,7 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { act, render, waitFor, fireEvent } from '@testing-library/react';
 import { Component, FC, useEffect } from 'react';
 import { GraphiQL } from './GraphiQL';
-import type { Fetcher } from '@graphiql/toolkit';
+import type { Fetcher, Transport } from '@graphiql/toolkit';
 import { buildSchema, introspectionFromSchema } from 'graphql';
 import {
   ToolbarButton,
@@ -36,12 +36,39 @@ describe('GraphiQL', () => {
   const noOpFetcher: Fetcher = () => {};
 
   describe('fetcher', () => {
-    it('should throw error without fetcher', () => {
+    it('should throw error without fetcher or transport', () => {
       const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
-      // @ts-expect-error fetcher is a required prop to GraphiQL
+      // @ts-expect-error -- one of fetcher | transport is required on GraphiQL
       expect(() => render(<GraphiQL />)).toThrow(
-        'The `GraphiQLProvider` component requires a `fetcher` function to be passed as prop.',
+        'The `GraphiQLProvider` component requires either a `transport` or a `fetcher` prop.',
+      );
+      spy.mockRestore();
+    });
+
+    it('is a type error to pass both `fetcher` and `transport`', () => {
+      // The assertion that matters here is the `@ts-expect-error` directive:
+      // if the XOR on `GraphiQLProps` regresses and both props become valid,
+      // tsc reports the directive as unused and this test fails to compile.
+      // The runtime guard in `GraphiQLProvider` belt-and-suspenders the type
+      // check.
+      const transport: Transport = {
+        send: async () => ({
+          ok: true,
+          body: { data: {} },
+          timing: { totalMs: 0 },
+          size: {},
+        }),
+      };
+      const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      expect(() =>
+        render(
+          // @ts-expect-error -- `fetcher` and `transport` are mutually exclusive
+          <GraphiQL fetcher={noOpFetcher} transport={transport} />,
+        ),
+      ).toThrow(
+        'The `fetcher` and `transport` props are mutually exclusive. Pass one or the other, not both.',
       );
       spy.mockRestore();
     });
diff --git a/packages/graphiql/src/GraphiQL.tsx b/packages/graphiql/src/GraphiQL.tsx
index 80ed26c5267..3845e01ff20 100644
--- a/packages/graphiql/src/GraphiQL.tsx
+++ b/packages/graphiql/src/GraphiQL.tsx
@@ -41,6 +41,7 @@ import {
   useGraphiQLActions,
   useMonaco,
 } from '@graphiql/react';
+import type { Fetcher, Transport } from '@graphiql/toolkit';
 import { HistoryStore, HISTORY_PLUGIN } from '@graphiql/plugin-history';
 import {
   DocExplorerStore,
@@ -57,13 +58,21 @@ import {
  * API docs for this live here:
  *
  * https://graphiql-test.netlify.app/typedoc/modules/graphiql.html#graphiqlprops
+ *
+ * Note: the XOR between `fetcher` and `transport` is preserved here explicitly.
+ * `Omit` flattens discriminated unions, so it has to be re-applied at this
+ * level so passing both props is a compile error at the `<GraphiQL>` call site.
  */
-export interface GraphiQLProps
-  // `children` prop should be optional
-  extends
-    GraphiQLInterfaceProps,
-    Omit<ComponentPropsWithoutRef<typeof GraphiQLProvider>, 'children'>,
-    Omit<ComponentPropsWithoutRef<typeof HistoryStore>, 'children'> {}
+export type GraphiQLProps = GraphiQLInterfaceProps &
+  Omit<ComponentPropsWithoutRef<typeof HistoryStore>, 'children'> &
+  Omit<
+    ComponentPropsWithoutRef<typeof GraphiQLProvider>,
+    'children' | 'fetcher' | 'transport'
+  > &
+  (
+    | { fetcher: Fetcher; transport?: never }
+    | { transport: Transport; fetcher?: never }
+  );
 
 /**
  * The top-level React component for GraphiQL, intended to encompass the entire
diff --git a/packages/graphiql/src/cdn.ts b/packages/graphiql/src/cdn.ts
index 84a1296ba61..0f70a8dd265 100644
--- a/packages/graphiql/src/cdn.ts
+++ b/packages/graphiql/src/cdn.ts
@@ -6,7 +6,12 @@
  */
 import { version } from 'react';
 import * as GraphiQLReact from '@graphiql/react';
-import { createGraphiQLFetcher, createLocalStorage } from '@graphiql/toolkit';
+import {
+  createGraphiQLFetcher,
+  createTransport,
+  createLocalStorage,
+} from '@graphiql/toolkit';
+import { createClient as createWsClient } from 'graphql-ws';
 import * as GraphQL from 'graphql';
 import { GraphiQL } from './GraphiQL';
 import './setup-workers/vite';
@@ -29,7 +34,18 @@ if (majorVersion < 16) {
  */
 export default Object.assign(GraphiQL, {
   /**
-   * This function is needed in order to easily create a fetcher function.
+   * This function is needed in order to easily create a transport function.
+   */
+  createTransport,
+  /**
+   * `graphql-ws`'s `createClient`, exposed on the CDN bundle so consumers can
+   * construct a `subscriptionClient` to pass to `GraphiQL.createTransport`
+   * without needing a separate bundler step. For SSE, load `graphql-sse`
+   * separately; its `createClient` is signature-compatible.
+   */
+  createWsClient,
+  /**
+   * @deprecated Use `GraphiQL.createTransport` instead.
    */
   createFetcher: createGraphiQLFetcher,
   /**
diff --git a/packages/graphiql/src/e2e.ts b/packages/graphiql/src/e2e.ts
index 69829ff26ab..b422ac99bb6 100644
--- a/packages/graphiql/src/e2e.ts
+++ b/packages/graphiql/src/e2e.ts
@@ -99,9 +99,11 @@ const root = ReactDOM.createRoot(document.getElementById('graphiql')!);
 const graphqlVersion = GraphiQL.GraphQL.version;
 
 const props: ComponentProps<typeof GraphiQL> = {
-  fetcher: GraphiQL.createFetcher({
+  transport: GraphiQL.createTransport({
     url: getSchemaUrl(),
-    subscriptionUrl: 'ws://localhost:8081/subscriptions',
+    subscriptionClient: GraphiQL.createWsClient({
+      url: 'ws://localhost:8081/subscriptions',
+    }),
   }),
 
   initialQuery: parameters.query,
diff --git a/yarn.lock b/yarn.lock
index cf164b5cf50..143b077f986 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -13977,6 +13977,7 @@ __metadata:
     cypress: "npm:^13.13.2"
     cypress-axe: "npm:^1"
     graphql: "npm:^16.11.0"
+    graphql-ws: "npm:^5.5.5"
     lightningcss: "npm:^1.29.3"
     react: "npm:^19.1.0"
     react-compiler-runtime: "npm:19.1.0-rc.1"

From 75f810428d719699aa528b0f6ab6c96f3e8db0a6 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 5 Jun 2026 17:56:14 -0700
Subject: [PATCH 36/38] format release.yml

---
 .github/workflows/release.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8250b2deccd..84281db92e7 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -44,7 +44,7 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version-file: ".node-version"
+          node-version-file: '.node-version'
           cache: yarn
 
       - run: yarn install --immutable
@@ -102,7 +102,7 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version-file: ".node-version"
+          node-version-file: '.node-version'
           cache: yarn
 
       - run: yarn install --immutable

From 8b700579e1d8c62870ad7059eb094527b14c0eaf Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Fri, 5 Jun 2026 19:47:50 -0700
Subject: [PATCH 37/38] v6: polyfill `localStorage` in test setup for Node 24 +
 jsdom (#4334)

Node 24 ships with a `jsdom` version that defines `window` but leaves
`localStorage` undefined, which causes `StorageAPI` to throw on
construction in unit tests. This adds a minimal in-memory `localStorage`
polyfill to the vitest setup files for `@graphiql/react` and
`@graphiql/toolkit`, gated on `typeof localStorage === 'undefined'` so
it has no effect in environments where the real API is present. The
toolkit package previously had no setup file, so this also wires one
into its `vitest.config.mts`.
---
 packages/graphiql-react/setup-files.ts      | 22 +++++++++++++++++++++
 packages/graphiql-toolkit/setup-files.ts    | 21 ++++++++++++++++++++
 packages/graphiql-toolkit/vitest.config.mts |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 packages/graphiql-toolkit/setup-files.ts

diff --git a/packages/graphiql-react/setup-files.ts b/packages/graphiql-react/setup-files.ts
index c40d88eff47..0d89e8954dc 100644
--- a/packages/graphiql-react/setup-files.ts
+++ b/packages/graphiql-react/setup-files.ts
@@ -2,6 +2,28 @@ import { vi, afterEach } from 'vitest';
 import '@testing-library/jest-dom/vitest';
 import { cleanup } from '@testing-library/react';
 
+// Node 24 + jsdom defines `window` but not `localStorage`. Polyfill with a
+// minimal in-memory implementation so StorageAPI can construct without error.
+if (typeof localStorage === 'undefined') {
+  const store = new Map<string, string>();
+  globalThis.localStorage = {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem(key: string, value: string) {
+      store.set(key, value);
+    },
+    removeItem(key: string) {
+      store.delete(key);
+    },
+    clear() {
+      store.clear();
+    },
+    get length() {
+      return store.size;
+    },
+    key: (index: number) => [...store.keys()][index] ?? null,
+  };
+}
+
 afterEach(cleanup);
 
 // to make it works like Jest (auto-mocking)
diff --git a/packages/graphiql-toolkit/setup-files.ts b/packages/graphiql-toolkit/setup-files.ts
new file mode 100644
index 00000000000..3085516fcf9
--- /dev/null
+++ b/packages/graphiql-toolkit/setup-files.ts
@@ -0,0 +1,21 @@
+// Node 24 + jsdom defines `window` but not `localStorage`. Polyfill with a
+// minimal in-memory implementation so StorageAPI can construct without error.
+if (typeof localStorage === 'undefined') {
+  const store = new Map<string, string>();
+  globalThis.localStorage = {
+    getItem: (key: string) => store.get(key) ?? null,
+    setItem(key: string, value: string) {
+      store.set(key, value);
+    },
+    removeItem(key: string) {
+      store.delete(key);
+    },
+    clear() {
+      store.clear();
+    },
+    get length() {
+      return store.size;
+    },
+    key: (index: number) => [...store.keys()][index] ?? null,
+  };
+}
diff --git a/packages/graphiql-toolkit/vitest.config.mts b/packages/graphiql-toolkit/vitest.config.mts
index 647a9e54c8c..e95ac9771fd 100644
--- a/packages/graphiql-toolkit/vitest.config.mts
+++ b/packages/graphiql-toolkit/vitest.config.mts
@@ -3,5 +3,6 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     environment: 'jsdom',
+    setupFiles: ['./setup-files.ts'],
   },
 });

From 0bd32a18c06fcca853cfd155538ccf50f6a3fc90 Mon Sep 17 00:00:00 2001
From: Trevor Scheer <trevor.scheer@gmail.com>
Date: Sat, 6 Jun 2026 15:51:30 -0700
Subject: [PATCH 38/38] v6: Add `ResponseTreeView` (#4335)

## Summary

Adds `ResponseTreeView`, a custom collapsible tree renderer for GraphQL
response JSON. When the user switches to the Tree view in the response
pane, they now see the actual response rendered as an expandable tree
rather than a placeholder message. Top-level keys are expanded by
default; nested objects and arrays start collapsed with a summary
showing their child count. Values are colored by type to match the
editor's tokenizer palette: strings in blue, numbers in orange, booleans
in purple, and null in muted gray.

## Test plan

- [x] Open the example app, run a query, and switch the response pane to
Tree view. Verify the response renders as a tree with the top level
expanded.
- [x] Click a collapsed object or array node and confirm it expands to
show children. Click again to confirm it collapses.
- [x] Confirm `aria-expanded` updates correctly on each toggle button
(check with browser DevTools or a screen reader).
- [x] Switch back to JSON view and verify the Monaco editor reappears
with the response intact.
- [x] Run a query that returns nested objects more than two levels deep.
Confirm only depth 0 is expanded by default; click to drill in.
- [x] Check the tree renders correctly in both dark and light themes.
---
 .changeset/response-tree-view.md              |   5 +
 .../graphiql-react/src/components/index.ts    |   2 +
 .../src/components/response-editor.tsx        |  36 ++--
 .../components/response-tree-view/index.css   |  68 ++++++
 .../components/response-tree-view/index.tsx   | 193 ++++++++++++++++++
 .../response-tree-view.stories.ts             | 126 ++++++++++++
 .../response-tree-view.test.tsx               | 154 ++++++++++++++
 resources/custom-words.txt                    |   6 +
 8 files changed, 575 insertions(+), 15 deletions(-)
 create mode 100644 .changeset/response-tree-view.md
 create mode 100644 packages/graphiql-react/src/components/response-tree-view/index.css
 create mode 100644 packages/graphiql-react/src/components/response-tree-view/index.tsx
 create mode 100644 packages/graphiql-react/src/components/response-tree-view/response-tree-view.stories.ts
 create mode 100644 packages/graphiql-react/src/components/response-tree-view/response-tree-view.test.tsx

diff --git a/.changeset/response-tree-view.md b/.changeset/response-tree-view.md
new file mode 100644
index 00000000000..6927e999104
--- /dev/null
+++ b/.changeset/response-tree-view.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/react': minor
+---
+
+Add `ResponseTreeView` component for the response pane's Tree view. Renders GraphQL response JSON as a collapsible tree with type-colored values. Top-level nodes expand by default; deeper levels are collapsed. Selecting "Tree" in the response pane view toggle now shows the tree instead of a placeholder.
diff --git a/packages/graphiql-react/src/components/index.ts b/packages/graphiql-react/src/components/index.ts
index a229d3cb622..183e741cb23 100644
--- a/packages/graphiql-react/src/components/index.ts
+++ b/packages/graphiql-react/src/components/index.ts
@@ -39,3 +39,5 @@ export { ActivityRail } from './activity-rail';
 export type { ActivityRailProps } from './activity-rail';
 export { ResponseHeader } from './response-header';
 export type { ResponseHeaderProps } from './response-header';
+export { ResponseTreeView } from './response-tree-view';
+export type { ResponseTreeViewProps } from './response-tree-view';
diff --git a/packages/graphiql-react/src/components/response-editor.tsx b/packages/graphiql-react/src/components/response-editor.tsx
index 2a90ee45f56..2f6fa06b63a 100644
--- a/packages/graphiql-react/src/components/response-editor.tsx
+++ b/packages/graphiql-react/src/components/response-editor.tsx
@@ -4,6 +4,7 @@ import { createRoot, Root } from 'react-dom/client';
 import { useGraphiQL, useGraphiQLActions } from './provider';
 import { ImagePreview } from './image-preview';
 import { ResponseHeader } from './response-header';
+import { ResponseTreeView } from './response-tree-view';
 import {
   getOrCreateModel,
   createEditor,
@@ -195,22 +196,27 @@ export const ResponseEditor: FC<ResponseEditorProps> = ({
           onCopy={handleCopy}
         />
       )}
-      {responseView === 'json' ? (
-        <section
-          ref={ref}
-          aria-label="Result Window"
-          aria-live="polite"
-          aria-atomic="true"
-          tabIndex={0}
-          onKeyDown={onEditorContainerKeyDown}
-          className="result-window"
-        />
-      ) : (
+      <section
+        ref={ref}
+        aria-label="Result Window"
+        aria-live="polite"
+        aria-atomic="true"
+        tabIndex={0}
+        onKeyDown={onEditorContainerKeyDown}
+        className="result-window"
+        hidden={responseView !== 'json'}
+      />
+      {responseView === 'tree' &&
+        (lastResponse ? (
+          <ResponseTreeView data={lastResponse.body} />
+        ) : (
+          <div className="graphiql-response-empty-state" role="status">
+            <span>Run a query to see the tree view.</span>
+          </div>
+        ))}
+      {responseView === 'table' && (
         <div className="graphiql-response-empty-state" role="status">
-          <span>
-            {responseView === 'tree' ? 'Tree' : 'Table'} view is not yet
-            available.
-          </span>
+          <span>Table view is not yet available.</span>
         </div>
       )}
     </div>
diff --git a/packages/graphiql-react/src/components/response-tree-view/index.css b/packages/graphiql-react/src/components/response-tree-view/index.css
new file mode 100644
index 00000000000..43fbcbbca82
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-tree-view/index.css
@@ -0,0 +1,68 @@
+.graphiql-response-tree {
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-mono);
+  line-height: 1.6;
+  color: oklch(var(--fg-default));
+  padding: var(--px-12) var(--px-16);
+  overflow: auto;
+  flex: 1;
+  min-height: 0;
+}
+
+.graphiql-tree-row {
+  display: flex;
+  align-items: baseline;
+  gap: var(--px-4);
+  white-space: nowrap;
+}
+
+.graphiql-tree-key {
+  color: oklch(var(--fg-default));
+  flex-shrink: 0;
+}
+
+.graphiql-tree-colon {
+  color: oklch(var(--fg-muted));
+  flex-shrink: 0;
+}
+
+.graphiql-tree-summary {
+  color: oklch(var(--fg-muted));
+}
+
+/* Scalar value colors matching the editor tokenizer palette */
+.graphiql-tree-string {
+  color: oklch(var(--accent-blue));
+}
+
+.graphiql-tree-number {
+  color: oklch(var(--accent-orange));
+}
+
+.graphiql-tree-bool {
+  color: oklch(var(--accent-purple));
+}
+
+.graphiql-tree-null {
+  color: oklch(var(--fg-muted));
+  font-style: italic;
+}
+
+.graphiql-tree-toggle {
+  background: transparent;
+  border: 0;
+  padding: 0;
+  cursor: pointer;
+  color: oklch(var(--fg-muted));
+  font-family: inherit;
+  font-size: inherit;
+  line-height: inherit;
+  flex-shrink: 0;
+  width: 14px;
+  text-align: center;
+  user-select: none;
+}
+
+.graphiql-tree-toggle:hover {
+  color: oklch(var(--fg-default));
+}
diff --git a/packages/graphiql-react/src/components/response-tree-view/index.tsx b/packages/graphiql-react/src/components/response-tree-view/index.tsx
new file mode 100644
index 00000000000..0d797f212c2
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-tree-view/index.tsx
@@ -0,0 +1,193 @@
+'use no memo';
+
+import { useState, type FC } from 'react';
+import './index.css';
+
+export type ResponseTreeViewProps = {
+  /** The JSON value to render. Typically the parsed response body. */
+  data: unknown;
+  /**
+   * Nodes at depth < this value start expanded; deeper nodes start collapsed.
+   * @default 1
+   */
+  initiallyExpandedDepth?: number;
+};
+
+export const ResponseTreeView: FC<ResponseTreeViewProps> = ({
+  data,
+  initiallyExpandedDepth = 1,
+}) => {
+  // Render top-level keys of an object directly (no synthetic root wrapper).
+  // This avoids the redundant `data > data > ...` nesting when the response
+  // envelope itself has a `data` key.
+  if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+    const entries = Object.entries(data as object);
+    return (
+      <div className="graphiql-response-tree">
+        {entries.map(([k, v]) => (
+          <TreeNode
+            key={k}
+            name={k}
+            value={v}
+            depth={0}
+            initiallyExpandedDepth={initiallyExpandedDepth}
+          />
+        ))}
+      </div>
+    );
+  }
+
+  // Non-object body (scalar, null, array) — render as a single unnamed value.
+  return (
+    <div className="graphiql-response-tree">
+      <RootValue value={data} initiallyExpandedDepth={initiallyExpandedDepth} />
+    </div>
+  );
+};
+
+type RootValueProps = {
+  value: unknown;
+  initiallyExpandedDepth: number;
+};
+
+// Renders a value that has no key label (used when the root body is not an object).
+const RootValue: FC<RootValueProps> = ({ value, initiallyExpandedDepth }) => {
+  const expandable = value !== null && typeof value === 'object';
+  const [open, setOpen] = useState(initiallyExpandedDepth > 0);
+
+  if (!expandable) {
+    const valueClass = `graphiql-tree-value graphiql-tree-${scalarClass(value)}`;
+    return (
+      <div className="graphiql-tree-row" style={{ paddingLeft: 0 }}>
+        <span className={valueClass}>{formatScalar(value)}</span>
+      </div>
+    );
+  }
+
+  const isArr = Array.isArray(value);
+  const entries = isArr
+    ? (value as unknown[]).map((v, i) => [String(i), v] as const)
+    : Object.entries(value as object);
+  const count = entries.length;
+  const summary = isArr ? `Array [${count}]` : `Object {${count}}`;
+
+  return (
+    <div>
+      <div className="graphiql-tree-row" style={{ paddingLeft: 0 }}>
+        <button
+          type="button"
+          className="graphiql-tree-toggle"
+          aria-label={open ? 'Collapse' : 'Expand'}
+          aria-expanded={open}
+          onClick={() => setOpen(o => !o)}
+        >
+          {open ? '▾' : '▸'}
+        </button>
+        <span className="graphiql-tree-summary">{summary}</span>
+      </div>
+      {open && (
+        <div>
+          {entries.map(([k, v]) => (
+            <TreeNode
+              key={k}
+              name={k}
+              value={v}
+              depth={1}
+              initiallyExpandedDepth={initiallyExpandedDepth}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+type TreeNodeProps = {
+  name: string;
+  value: unknown;
+  depth: number;
+  initiallyExpandedDepth: number;
+};
+
+const TreeNode: FC<TreeNodeProps> = ({
+  name,
+  value,
+  depth,
+  initiallyExpandedDepth,
+}) => {
+  const expandable = value !== null && typeof value === 'object';
+  const [open, setOpen] = useState(depth < initiallyExpandedDepth);
+
+  if (!expandable) {
+    const valueClass = `graphiql-tree-value graphiql-tree-${scalarClass(value)}`;
+    return (
+      <div className="graphiql-tree-row" style={{ paddingLeft: depth * 16 }}>
+        <span className="graphiql-tree-key">{name}</span>
+        <span className="graphiql-tree-colon">:</span>
+        <span className={valueClass}>{formatScalar(value)}</span>
+      </div>
+    );
+  }
+
+  const isArr = Array.isArray(value);
+  const entries = isArr
+    ? (value as unknown[]).map((v, i) => [String(i), v] as const)
+    : Object.entries(value as object);
+  const count = entries.length;
+  const summary = isArr ? `Array [${count}]` : `Object {${count}}`;
+
+  return (
+    <div>
+      <div className="graphiql-tree-row" style={{ paddingLeft: depth * 16 }}>
+        <button
+          type="button"
+          className="graphiql-tree-toggle"
+          aria-label={open ? 'Collapse' : 'Expand'}
+          aria-expanded={open}
+          onClick={() => setOpen(o => !o)}
+        >
+          {open ? '▾' : '▸'}
+        </button>
+        <span className="graphiql-tree-key">{name}</span>
+        <span className="graphiql-tree-colon">:</span>
+        <span className="graphiql-tree-summary">{summary}</span>
+      </div>
+      {open && (
+        <div>
+          {entries.map(([k, v]) => (
+            <TreeNode
+              key={k}
+              name={k}
+              value={v}
+              depth={depth + 1}
+              initiallyExpandedDepth={initiallyExpandedDepth}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+function scalarClass(v: unknown): string {
+  if (typeof v === 'string') {
+    return 'string';
+  }
+  if (typeof v === 'number') {
+    return 'number';
+  }
+  if (typeof v === 'boolean') {
+    return 'bool';
+  }
+  return 'null';
+}
+
+function formatScalar(v: unknown): string {
+  if (typeof v === 'string') {
+    return JSON.stringify(v);
+  }
+  if (v === null) {
+    return 'null';
+  }
+  return String(v);
+}
diff --git a/packages/graphiql-react/src/components/response-tree-view/response-tree-view.stories.ts b/packages/graphiql-react/src/components/response-tree-view/response-tree-view.stories.ts
new file mode 100644
index 00000000000..760fe09494a
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-tree-view/response-tree-view.stories.ts
@@ -0,0 +1,126 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ResponseTreeView } from './';
+
+const meta: Meta<typeof ResponseTreeView> = {
+  title: 'Components/ResponseTreeView',
+  component: ResponseTreeView,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ResponseTreeView>;
+
+export const NullResponse: Story = {
+  name: 'Null value',
+  args: {
+    data: null,
+  },
+};
+
+export const ScalarString: Story = {
+  name: 'Scalar string',
+  args: {
+    data: 'Hello, GraphQL!',
+  },
+};
+
+export const SimpleObject: Story = {
+  name: 'Simple object (top level expanded)',
+  args: {
+    data: {
+      data: {
+        id: '1',
+        name: 'Luke Skywalker',
+        height: 172,
+        mass: 77,
+        appearsIn: ['NEWHOPE', 'EMPIRE', 'JEDI'],
+      },
+    },
+  },
+};
+
+export const NestedObject: Story = {
+  name: 'Nested object (deeper levels collapsed)',
+  args: {
+    data: {
+      data: {
+        hero: {
+          name: 'R2-D2',
+          friends: [
+            {
+              name: 'Luke Skywalker',
+              homeworld: { name: 'Tatooine' },
+            },
+            {
+              name: 'Han Solo',
+              homeworld: { name: 'Corellia' },
+            },
+            {
+              name: 'Leia Organa',
+              homeworld: { name: 'Alderaan' },
+            },
+          ],
+        },
+      },
+    },
+  },
+};
+
+export const LargeArray: Story = {
+  name: 'Large array (collapsed)',
+  args: {
+    data: {
+      data: {
+        allPeople: {
+          edges: Array.from({ length: 82 }, (_, i) => ({
+            node: { id: String(i + 1), name: `Person ${i + 1}` },
+          })),
+        },
+      },
+    },
+    initiallyExpandedDepth: 1,
+  },
+};
+
+export const MixedTypes: Story = {
+  name: 'Mixed scalar types',
+  args: {
+    data: {
+      data: {
+        string: 'hello',
+        number: 42,
+        float: 3.14,
+        boolean: true,
+        falsyBool: false,
+        nullValue: null,
+        emptyString: '',
+      },
+    },
+  },
+};
+
+export const EmptyObject: Story = {
+  name: 'Empty object',
+  args: {
+    data: {},
+  },
+};
+
+export const ErrorResponse: Story = {
+  name: 'Error response',
+  args: {
+    data: {
+      errors: [
+        {
+          message: 'Cannot query field "notARealField" on type "Query".',
+          locations: [{ line: 3, column: 5 }],
+          path: ['hero', 'notARealField'],
+        },
+      ],
+      data: null,
+    },
+  },
+};
diff --git a/packages/graphiql-react/src/components/response-tree-view/response-tree-view.test.tsx b/packages/graphiql-react/src/components/response-tree-view/response-tree-view.test.tsx
new file mode 100644
index 00000000000..5c30fd13e67
--- /dev/null
+++ b/packages/graphiql-react/src/components/response-tree-view/response-tree-view.test.tsx
@@ -0,0 +1,154 @@
+'use no memo';
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ResponseTreeView } from './';
+
+describe('ResponseTreeView', () => {
+  it('renders a string scalar value', () => {
+    render(<ResponseTreeView data="hello" />);
+    expect(screen.getByText(/"hello"/)).toBeInTheDocument();
+  });
+
+  it('renders a number scalar value', () => {
+    render(<ResponseTreeView data={42} />);
+    expect(screen.getByText('42')).toBeInTheDocument();
+  });
+
+  it('renders null', () => {
+    render(<ResponseTreeView data={null} />);
+    expect(screen.getByText('null')).toBeInTheDocument();
+  });
+
+  it('renders boolean false', () => {
+    render(<ResponseTreeView data={false} />);
+    expect(screen.getByText('false')).toBeInTheDocument();
+  });
+
+  it('renders top-level object keys directly (no synthetic root wrapper)', () => {
+    render(<ResponseTreeView data={{ data: { id: '1' }, errors: [] }} />);
+    // Both top-level envelope keys appear directly — no extra wrapper row
+    expect(screen.getByText('data')).toBeInTheDocument();
+    expect(screen.getByText('errors')).toBeInTheDocument();
+  });
+
+  it('renders a nested object with child count summary when collapsed', () => {
+    // The summary appears on nested object values, not the top-level keys
+    render(
+      <ResponseTreeView
+        data={{ nested: { a: 1, b: 2 } }}
+        initiallyExpandedDepth={0}
+      />,
+    );
+    expect(screen.getByText('Object {2}')).toBeInTheDocument();
+  });
+
+  it('renders an array with child count summary when collapsed', () => {
+    render(<ResponseTreeView data={[1, 2, 3]} initiallyExpandedDepth={0} />);
+    expect(screen.getByText('Array [3]')).toBeInTheDocument();
+  });
+
+  it('top-level object keys are expanded by default', () => {
+    render(<ResponseTreeView data={{ name: 'GraphiQL' }} />);
+    // child value should be visible without any interaction
+    expect(screen.getByText('name')).toBeInTheDocument();
+    expect(screen.getByText(/"GraphiQL"/)).toBeInTheDocument();
+  });
+
+  it('nested objects are collapsed by default', () => {
+    // top-level keys (depth 0) expand by default; deeper keys do not.
+    render(
+      <ResponseTreeView data={{ outer: { middle: { inner: 'value' } } }} />,
+    );
+    // `outer` (depth 0) is expanded — `middle` is visible
+    expect(screen.getByText('outer')).toBeInTheDocument();
+    expect(screen.getByText('middle')).toBeInTheDocument();
+    // `middle` (depth 1) is collapsed — `inner` is not visible
+    expect(screen.queryByText('inner')).toBeNull();
+  });
+
+  it('expands a collapsed node on toggle click', async () => {
+    const user = userEvent.setup();
+    render(
+      <ResponseTreeView data={{ outer: { middle: { inner: 'value' } } }} />,
+    );
+    // `middle` (depth 1) starts collapsed
+    const collapsed = screen
+      .getAllByRole('button')
+      .find(b => b.getAttribute('aria-expanded') === 'false');
+    expect(collapsed).toBeDefined();
+    await user.click(collapsed!);
+    expect(screen.getByText('inner')).toBeInTheDocument();
+  });
+
+  it('collapses an expanded top-level key on toggle click', async () => {
+    const user = userEvent.setup();
+    render(<ResponseTreeView data={{ hero: { id: '1' } }} />);
+    // hero is expanded by default (depth 0 < initiallyExpandedDepth 1)
+    const toggle = screen.getByRole('button', { name: /collapse/i });
+    await user.click(toggle);
+    // hero's child `id` is no longer visible
+    expect(screen.queryByText('id')).toBeNull();
+  });
+
+  it('toggle button has correct aria-expanded when open', () => {
+    // Need a nested object so there's a toggle button at the top level
+    render(<ResponseTreeView data={{ group: { a: 1 } }} />);
+    const btn = screen.getByRole('button', { name: /collapse/i });
+    expect(btn).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('toggle button has correct aria-expanded when closed', () => {
+    render(
+      <ResponseTreeView
+        data={{ group: { a: 1 } }}
+        initiallyExpandedDepth={0}
+      />,
+    );
+    const btn = screen.getByRole('button', { name: /expand/i });
+    expect(btn).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('renders a large array count correctly', () => {
+    render(
+      <ResponseTreeView
+        data={Array.from({ length: 100 }, (_, i) => i)}
+        initiallyExpandedDepth={0}
+      />,
+    );
+    expect(screen.getByText('Array [100]')).toBeInTheDocument();
+  });
+
+  it('renders empty object with no rows', () => {
+    render(<ResponseTreeView data={{}} />);
+    expect(
+      document.querySelector('.graphiql-response-tree'),
+    ).toBeInTheDocument();
+    expect(document.querySelector('.graphiql-tree-row')).toBeNull();
+  });
+
+  it('renders empty array', () => {
+    render(<ResponseTreeView data={[]} initiallyExpandedDepth={0} />);
+    expect(screen.getByText('Array [0]')).toBeInTheDocument();
+  });
+
+  it('renders array items with numeric keys when expanded', () => {
+    render(<ResponseTreeView data={['a', 'b']} initiallyExpandedDepth={1} />);
+    expect(screen.getByText('0')).toBeInTheDocument();
+    expect(screen.getByText('1')).toBeInTheDocument();
+  });
+
+  it('renders sibling top-level envelope keys (data + errors)', () => {
+    render(
+      <ResponseTreeView
+        data={{
+          data: { hero: { name: 'R2-D2' } },
+          errors: [{ message: 'oops' }],
+        }}
+      />,
+    );
+    expect(screen.getByText('data')).toBeInTheDocument();
+    expect(screen.getByText('errors')).toBeInTheDocument();
+  });
+});
diff --git a/resources/custom-words.txt b/resources/custom-words.txt
index 01c1e6ffce9..2458d69d5a1 100644
--- a/resources/custom-words.txt
+++ b/resources/custom-words.txt
@@ -21,6 +21,7 @@ acao
 acmerc
 aivazis
 akshat
+alderaan
 alexey
 alok
 amfoss
@@ -52,6 +53,7 @@ codegen
 codemirror
 codesandbox
 codespaces
+corellia
 codicon
 colmena
 combobox
@@ -97,6 +99,7 @@ graphqls
 ˈɡrafək
 harshith
 headlessui
+homeworld
 heyenbrock
 hola
 htmling
@@ -118,6 +121,7 @@ keycap
 kumar
 languageservice
 leebyron
+leia
 Leko
 LekoArts
 lezer
@@ -206,6 +210,7 @@ sfc's
 sgrove
 simha
 singleline
+skywalker
 snyk
 socker
 sonarjs
@@ -223,6 +228,7 @@ svgo
 svgr
 tanay
 tanaypratap
+tatooine
 testid
 testonly
 therox