v6: Align GraphQL syntax colors and color type names by category (#4403)

trevor-scheer · web-flow · commit b5eb5986d464 · 2026-07-11T14:25:43.000-07:00
## Summary This PR does two related things for GraphQL identifier coloring across the first-party plugins. **1. Align colors across plugins.** Type names, field names, and argument names now use the same colors across the doc explorer, history, and query builder. Doc explorer was already internally consistent (orange types, green fields, purple arguments), so it's the reference the other two now follow. History's saved query labels (previously plain foreground text) are now the same green as field names. Query builder previously colored composite return types and type-condition names blue and left argument names uncolored; both now match doc explorer. **2. Color type names by category.** Instead of every type name being orange, type-name references are colored by GraphQL kind, so a field list is no longer a monotonous wall of orange: | Kind | Color | |---|---| | object / interface / union | orange | | scalar | blue | | enum | green | | input object | gold | This applies in the schema-aware plugins (doc explorer and query builder). The Monaco query editor is unchanged — it isn't schema-aware, so type names in query text stay orange. ### Public API The scheme is exposed so third-party plugins can conform to it and retheme it: - Four CSS tokens — `--type-composite`, `--type-scalar`, `--type-enum`, `--type-input` — are the supported retheming surface (documented in `tokens.css`). - `typeCategory(type)` is exported from `@graphiql/react`; it buckets any GraphQL type into `'scalar' | 'enum' | 'input' | 'composite'`, unwrapping list/non-null wrappers. Class names, internal selectors, and the `data-type-kind` attribute remain private. Light-theme `--type-input` uses a darker gold than the dark theme so it clears WCAG AA as text (~5–6.5:1 against the doc-explorer surfaces). ## Test plan - [x] **Alignment:** Open the doc explorer, history, and query builder in the same session. A field name is the same green in all three; an argument name is the same purple in both doc explorer and query builder. - [x] **Category colors (doc explorer):** Browse a schema with mixed field types. Scalar return types (`String`/`Int`/`Boolean`/`ID`/custom scalars) are blue, enum types green, object/interface/union types orange, and input object types gold. - [x] **Category colors (query builder):** Expand the field tree. Scalar-returning fields are blue, enum-returning fields green, object/interface/union fields orange. - [x] **Arguments (doc explorer):** A field with an input-object argument shows the input type name in gold, clearly distinct from the purple argument name beside it. - [x] **Type conditions (query builder):** Expand an interface/union field's possible types. The `... on TypeName` labels are orange. - [x] **Search (doc explorer):** Search results show type names colored by the same category scheme. - [x] **History:** Saved query entries show their label/operation name in green. - [x] **Light theme:** Switch themes and spot-check the same views. All four category colors stay legible against the panel background — the gold in particular should read as a clear dark gold, not washed out. Refs: #4219
diff --git a/.changeset/plugin-syntax-color-alignment.md b/.changeset/plugin-syntax-color-alignment.md
@@ -0,0 +1,13 @@
+---
+'@graphiql/react': patch
+'@graphiql/plugin-history': patch
+'@graphiql/plugin-query-builder': patch
+---
+
+Align GraphQL syntax coloring across the doc explorer, history, and query builder plugins, so type names, field names, and argument names use the same colors everywhere.
+
+Type names are now colored by category — scalars blue, enums green, input
+objects gold, and objects/interfaces/unions orange — instead of uniform
+orange. The mapping is exposed as public API: the `--type-scalar`,
+`--type-enum`, `--type-input`, and `--type-composite` CSS tokens (retheming
+surface) and the `typeCategory` helper exported from `@graphiql/react`.
diff --git a/docs/migration/graphiql-6.0.0.md b/docs/migration/graphiql-6.0.0.md
@@ -41,6 +41,7 @@ The new tokens are stored as `L% C H` component triplets (lightness percent, chr
 - **Borders:** `--border-default`, `--border-muted`, `--border-strong`
 - **Foreground:** `--fg-default`, `--fg-strong`, `--fg-muted`, `--fg-subtle`, `--fg-disabled`, `--fg-dim`
 - **Accents:** `--accent-blue`, `--accent-green`, `--accent-green-light`, `--accent-yellow`, `--accent-orange`, `--accent-red`, `--accent-purple`, `--accent-pink`
+- **Type-name categories:** `--type-composite`, `--type-scalar`, `--type-enum`, `--type-input`
 - **Run button:** `--btn-primary`, `--btn-primary-border`
 - **Radii:** `--radius-sm`, `--radius-md`, `--radius-lg`
 - **Shadow:** `--shadow-popover`
@@ -49,6 +50,29 @@ There is no published mapping from the nine v5 `--color-*` names to these — th
 
 The v5 variables are still documented in the [`@graphiql/react` README](../../packages/graphiql-react/README.md#theming); the new token file itself, [`tokens.css`](../../packages/graphiql-react/src/style/tokens.css), is the source of truth for the v6 set until the README catches up.
 
+### Type-name colors
+
+In the schema-aware plugins — the doc explorer and the query builder — type-name references are colored by their GraphQL kind rather than all sharing one color. This makes a field list easier to scan: leaf types stand out from the objects you drill into.
+
+| Kind                     | Token              | Default |
+| ------------------------ | ------------------ | ------- |
+| object, interface, union | `--type-composite` | orange  |
+| scalar                   | `--type-scalar`    | blue    |
+| enum                     | `--type-enum`      | green   |
+| input object             | `--type-input`     | gold    |
+
+These four `--type-*` tokens are the supported surface for retheming type-name colors. By default each aliases an accent token (`--type-scalar` resolves to `--accent-blue`, and so on), so you can retint either the accent or the `--type-*` token directly:
+
+```css
+[data-theme='dark'] {
+  --type-scalar: 75% 0.15 200; /* recolor scalar type names */
+}
+```
+
+If you're building your own plugin that renders type names and want it to match, `@graphiql/react` exports a `typeCategory(type)` helper that maps any GraphQL type to `'scalar' | 'enum' | 'input' | 'composite'` (unwrapping list and non-null wrappers). Apply the corresponding `--type-*` token to your markup; the attribute and class names GraphiQL uses internally are not part of the public API.
+
+The Monaco query editor is not schema-aware — it can't tell a scalar from an object by name alone — so type names in the query text itself keep a single color. This categorization applies only to the schema-driven plugin UIs.
+
 ### Retheming example
 
 To retint the accent color and canvas background for dark mode:
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/__tests__/type-link.spec.tsx b/packages/graphiql-plugin-doc-explorer/src/components/__tests__/type-link.spec.tsx
@@ -1,7 +1,14 @@
 import { describe, it, expect } from 'vitest';
 import { FC, useEffect } from 'react';
 import { fireEvent, render } from '@testing-library/react';
-import { GraphQLNonNull, GraphQLList, GraphQLString } from 'graphql';
+import {
+  GraphQLNonNull,
+  GraphQLList,
+  GraphQLString,
+  GraphQLEnumType,
+  GraphQLObjectType,
+  GraphQLInputObjectType,
+} from 'graphql';
 import { docExplorerStore, useDocExplorer } from '../../context';
 import { TypeLink } from '../type-link';
 import { unwrapType } from './test-utils';
@@ -70,4 +77,46 @@ describe('TypeLink', () => {
     rerender(<TypeLinkWithContext type={GraphQLString} />);
     expect(container).toHaveTextContent('String');
   });
+
+  const enumT = new GraphQLEnumType({
+    name: 'Episode',
+    values: { NEWHOPE: {} },
+  });
+  const objectT = new GraphQLObjectType({
+    name: 'Droid',
+    fields: { id: { type: GraphQLString } },
+  });
+  const inputT = new GraphQLInputObjectType({
+    name: 'ReviewInput',
+    fields: { stars: { type: GraphQLString } },
+  });
+
+  it('tags a scalar type with data-type-kind="scalar"', () => {
+    const { container } = render(<TypeLinkWithContext type={GraphQLString} />);
+    expect(container.querySelector('a')).toHaveAttribute(
+      'data-type-kind',
+      'scalar',
+    );
+  });
+  it('tags an enum type with data-type-kind="enum"', () => {
+    const { container } = render(<TypeLinkWithContext type={enumT} />);
+    expect(container.querySelector('a')).toHaveAttribute(
+      'data-type-kind',
+      'enum',
+    );
+  });
+  it('tags an object type with data-type-kind="composite"', () => {
+    const { container } = render(<TypeLinkWithContext type={objectT} />);
+    expect(container.querySelector('a')).toHaveAttribute(
+      'data-type-kind',
+      'composite',
+    );
+  });
+  it('tags an input object type with data-type-kind="input"', () => {
+    const { container } = render(<TypeLinkWithContext type={inputT} />);
+    expect(container.querySelector('a')).toHaveAttribute(
+      'data-type-kind',
+      'input',
+    );
+  });
 });
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css b/packages/graphiql-plugin-doc-explorer/src/components/arguments-list.css
@@ -78,15 +78,7 @@
 }
 
 .graphiql-doc-explorer-argument-type {
-  color: oklch(var(--accent-orange));
-
-  & .graphiql-doc-explorer-type-name {
-    color: oklch(var(--accent-orange));
-
-    &:hover {
-      text-decoration: underline;
-    }
-  }
+  color: oklch(var(--fg-default));
 }
 
 .graphiql-doc-explorer-argument-default {
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/field-card.css b/packages/graphiql-plugin-doc-explorer/src/components/field-card.css
@@ -26,15 +26,7 @@
 .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;
-    }
-  }
+  color: oklch(var(--fg-default));
 }
 
 .graphiql-doc-explorer-field-card-description {
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/fields-list.css b/packages/graphiql-plugin-doc-explorer/src/components/fields-list.css
@@ -104,18 +104,10 @@
   color: oklch(var(--fg-disabled));
 }
 
-/* Return type color — inherits from TypeLink */
+/* The type-name anchor colors itself by category (see type-link.css); this
+   wrapper only styles the surrounding list/non-null punctuation ([, ], !). */
 .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;
-    }
-  }
+  color: oklch(var(--fg-default));
 }
 
 /* Optional description */
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css b/packages/graphiql-plugin-doc-explorer/src/components/schema-documentation.css
@@ -55,9 +55,10 @@
   color: oklch(var(--fg-muted));
 }
 
-/* Type name in root rows — orange like TypeLink */
+/* Root operation types are always objects (composite). Plain spans, not
+   TypeLink anchors, so they need an explicit color. */
 .graphiql-doc-explorer-schema-root-row .graphiql-doc-explorer-type-name {
-  color: oklch(var(--accent-orange));
+  color: oklch(var(--type-composite));
 }
 
 /* All-types rows */
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx b/packages/graphiql-plugin-doc-explorer/src/components/search-row.tsx
@@ -20,6 +20,7 @@ import {
   KeycapHint,
   debounce,
   KEY_MAP,
+  typeCategory,
 } from '@graphiql/react';
 import { useDocExplorer, useDocExplorerActions } from '../context';
 import { useSearchResults } from './search';
@@ -163,7 +164,12 @@ export const SearchRow: FC = () => {
 };
 
 const SearchType: FC<{ type: GraphQLNamedType }> = ({ type }) => (
-  <span className="graphiql-doc-explorer-search-type">{type.name}</span>
+  <span
+    className="graphiql-doc-explorer-search-type"
+    data-type-kind={typeCategory(type)}
+  >
+    {type.name}
+  </span>
 );
 
 type SearchFieldProps = {
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/search.css b/packages/graphiql-plugin-doc-explorer/src/components/search.css
@@ -86,7 +86,19 @@
 }
 
 .graphiql-doc-explorer-search-type {
-  color: oklch(var(--accent-orange));
+  color: oklch(var(--type-composite));
+}
+
+.graphiql-doc-explorer-search-type[data-type-kind='scalar'] {
+  color: oklch(var(--type-scalar));
+}
+
+.graphiql-doc-explorer-search-type[data-type-kind='enum'] {
+  color: oklch(var(--type-enum));
+}
+
+.graphiql-doc-explorer-search-type[data-type-kind='input'] {
+  color: oklch(var(--type-input));
 }
 
 .graphiql-doc-explorer-search-field {
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-card.css b/packages/graphiql-plugin-doc-explorer/src/components/type-card.css
@@ -67,7 +67,7 @@
 
 a.graphiql-doc-explorer-type-card-implements-link {
   font-family: var(--font-family-mono);
-  color: oklch(var(--accent-orange));
+  color: oklch(var(--type-composite));
   text-decoration: none;
 
   &:hover {
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-link.css b/packages/graphiql-plugin-doc-explorer/src/components/type-link.css
@@ -1,12 +1,24 @@
 a.graphiql-doc-explorer-type-name {
-  color: oklch(var(--accent-orange));
+  color: oklch(var(--type-composite));
   text-decoration: none;
 
   &:hover {
     text-decoration: underline;
   }
 
   &:focus {
-    outline: oklch(var(--accent-orange)) auto 1px;
+    outline: currentColor auto 1px;
   }
 }
+
+a.graphiql-doc-explorer-type-name[data-type-kind='scalar'] {
+  color: oklch(var(--type-scalar));
+}
+
+a.graphiql-doc-explorer-type-name[data-type-kind='enum'] {
+  color: oklch(var(--type-enum));
+}
+
+a.graphiql-doc-explorer-type-name[data-type-kind='input'] {
+  color: oklch(var(--type-input));
+}
diff --git a/packages/graphiql-plugin-doc-explorer/src/components/type-link.tsx b/packages/graphiql-plugin-doc-explorer/src/components/type-link.tsx
@@ -1,5 +1,6 @@
 import type { FC } from 'react';
 import type { GraphQLType } from 'graphql';
+import { typeCategory } from '@graphiql/react';
 import { useDocExplorerActions } from '../context';
 import { renderType } from './utils';
 import './type-link.css';
@@ -17,6 +18,7 @@ export const TypeLink: FC<TypeLinkProps> = ({ type }) => {
   return renderType(type, def => (
     <a
       className="graphiql-doc-explorer-type-name"
+      data-type-kind={typeCategory(def)}
       onClick={event => {
         event.preventDefault();
         push({ name: def.name, def });
diff --git a/packages/graphiql-plugin-history/src/style.css b/packages/graphiql-plugin-history/src/style.css
@@ -83,7 +83,9 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  color: oklch(var(--fg-default));
+  /* The label is the operation/root field name, colored to match field names
+     in the doc explorer and query builder. */
+  color: oklch(var(--accent-green-light));
   font-family: var(--font-family-mono);
   font-size: var(--font-size-mono);
   text-align: left;
diff --git a/packages/graphiql-plugin-query-builder/src/components/__tests__/field-row.spec.tsx b/packages/graphiql-plugin-query-builder/src/components/__tests__/field-row.spec.tsx
@@ -44,6 +44,13 @@ const fieldWithArgs = new GraphQLObjectType({
   },
 });
 
+const typeWithEnumReturn = new GraphQLObjectType({
+  name: 'WithEnumReturn',
+  fields: {
+    episode: { type: EpisodeEnum },
+  },
+});
+
 const typeWithDeprecated = new GraphQLObjectType({
   name: 'WithDeprecated',
   fields: {
@@ -57,6 +64,7 @@ const friendsField = parentType.getFields()['friends']!;
 const heroField = fieldWithArgs.getFields()['hero']!;
 const legacyField = typeWithDeprecated.getFields()['legacy']!;
 const currentField = typeWithDeprecated.getFields()['current']!;
+const episodeField = typeWithEnumReturn.getFields()['episode']!;
 
 describe('FieldRow', () => {
   it('renders the field name', () => {
@@ -89,6 +97,38 @@ describe('FieldRow', () => {
     expect(screen.getByText('String')).toBeInTheDocument();
   });
 
+  it('marks a scalar return type with the --scalar modifier', () => {
+    const { container } = render(
+      <FieldRow
+        field={nameField}
+        path={[fieldSegment('hero')]}
+        selected={false}
+        hasChildren={false}
+        expanded={false}
+        onToggle={() => {}}
+        onExpand={() => {}}
+      />,
+    );
+    const typeEl = container.querySelector('.graphiql-qb-field-type');
+    expect(typeEl?.className).toContain('graphiql-qb-field-type--scalar');
+  });
+
+  it('marks an enum return type with the --enum modifier', () => {
+    const { container } = render(
+      <FieldRow
+        field={episodeField}
+        path={[]}
+        selected={false}
+        hasChildren={false}
+        expanded={false}
+        onToggle={() => {}}
+        onExpand={() => {}}
+      />,
+    );
+    const typeEl = container.querySelector('.graphiql-qb-field-type');
+    expect(typeEl?.className).toContain('graphiql-qb-field-type--enum');
+  });
+
   it('checkbox is unchecked when selected=false', () => {
     render(
       <FieldRow
diff --git a/packages/graphiql-plugin-query-builder/src/components/field-row.tsx b/packages/graphiql-plugin-query-builder/src/components/field-row.tsx
@@ -1,5 +1,9 @@
-import { ChevronDownIcon, MarkdownContent, Tooltip } from '@graphiql/react';
-import { getNamedType, isEnumType, isScalarType } from 'graphql';
+import {
+  ChevronDownIcon,
+  MarkdownContent,
+  Tooltip,
+  typeCategory,
+} from '@graphiql/react';
 import type { GraphQLField } from 'graphql';
 import type { FC } from 'react';
 import type { ArgValue } from '../lib/document-mutator';
@@ -57,10 +61,7 @@ export const FieldRow: FC<FieldRowProps> = ({
   const nameClassName = `graphiql-qb-field-name${
     deprecated ? ' graphiql-qb-field-name--deprecated' : ''
   }`;
-  // Color the type by its unwrapped named kind: scalars/enums are "leaf" types,
-  // everything else (object/interface/union) is "composite".
-  const namedType = getNamedType(field.type);
-  const isLeafType = isScalarType(namedType) || isEnumType(namedType);
+  const typeColorCategory = typeCategory(field.type);
 
   return (
     <div
@@ -127,11 +128,7 @@ export const FieldRow: FC<FieldRowProps> = ({
           </Tooltip>
         )}
         <span
-          className={
-            isLeafType
-              ? 'graphiql-qb-field-type'
-              : 'graphiql-qb-field-type graphiql-qb-field-type--composite'
-          }
+          className={`graphiql-qb-field-type graphiql-qb-field-type--${typeColorCategory}`}
         >
           {String(field.type)}
         </span>
diff --git a/packages/graphiql-plugin-query-builder/src/style.css b/packages/graphiql-plugin-query-builder/src/style.css
diff --git a/packages/graphiql-react/src/style/tokens.css b/packages/graphiql-react/src/style/tokens.css
diff --git a/packages/graphiql-react/src/utility/index.ts b/packages/graphiql-react/src/utility/index.ts
diff --git a/packages/graphiql-react/src/utility/type-category.test.ts b/packages/graphiql-react/src/utility/type-category.test.ts
diff --git a/packages/graphiql-react/src/utility/type-category.ts b/packages/graphiql-react/src/utility/type-category.ts

Original file line number	Diff line number	Diff line change
`@@ -55,9 +55,10 @@`
`55`	`55`	`color: oklch(var(--fg-muted));`
`56`	`56`	`}`
`57`	`57`
`58`		`-/* Type name in root rows — orange like TypeLink */`
	`58`	`+/* Root operation types are always objects (composite). Plain spans, not`
	`59`	`+ TypeLink anchors, so they need an explicit color. */`
`59`	`60`	`.graphiql-doc-explorer-schema-root-row .graphiql-doc-explorer-type-name {`
`60`		`- color: oklch(var(--accent-orange));`
	`61`	`+ color: oklch(var(--type-composite));`
`61`	`62`	`}`
`62`	`63`
`63`	`64`	`/* All-types rows */`