GraphiQL 2 Design

[timsuchanek]

As a continuation of the discussion in #978 (comment) - let's discuss the new GraphiQL 2 design proposal here in a dedicated GitHub discussion, so we can have multiple discussion threads here.
As a reminder about the design:

In the last GraphiQL WG meeting in January, I offered to work on the new design together with @julianbauer, who actually designed the GraphQL Playground. For people who don't know, I implemented the GraphQL Playground back in the days.

After the WG meeting in January, @orta , @acao, @julianbauer and I had a call about the design and where it should go.
We mostly aligned around the goals: Keep it simple initially, but extensible as well, to cater to all the awesome plugin ideas that folks have. Then later we can add more stuff (like tabs or all kind of fancy features)

I'd like to present you our GraphiQL 2 design proposal and would love to get your thoughts on this!
Here is the new design.

As it can be a bit complex and needs some explanations of the thoughts we had in the design process, here's a video we recorded to walk you through: https://grain.co/share/story/0546c630-bb5d-4f83-acd6-5688c20cabe8/cGpVhVJt786DedMVrOrfvY0dktFdcmVldC8UkkmI

Besides introducing a fresher, more modern look, we are suggesting a major change, which we believe could significantly improve the developer experience:
Moving Docs and Docs explorer into one. You might know the docs explorer that onegraph pioneered. We believe, that the docs and the explorer, which allows you to construct queries, can be one. This is probably the most ambitious and potentially controversial topic - especially here we'd love to get your thoughts.

Looking forward to your feedback!

[n1ru4l]

Some feedback:

I don't like the pluralization Queries, Mutations, and Subscriptions. Query, Mutation, or Subscription makes more sense as those are fields on the Query, Mutation, or Subscription object types.

I am aware that often people use the word Queries in the context of describing the fields that can be selected on the root query type.

Example:

• You can send allFilms, person, and species queries.
• Here you can see the available queries/mutations/subscriptions

IMHO correct lingo:

• You can send a query operation selecting the allFilms, person, and species fields.
• Here you can see the available query/mutation/subscription fields

So my proposal here would be to either use Query/Mutation/Subscription or Query Fields/Mutation Fields/Subscription Fields.

---

I am skeptical about merging both the documentation explorer and operation builder UI into a single element. It is really hard to imagine whether it will work out or not just from looking at the design drafts. I am looking forward to actually play around with it or seeing some "scripted" flow examples!

[EdwinJackson]

I would like to say that I think Query/Mutation/Subscription is the right choice here and that Query Fields/Mutation Fields/Subscription Fields is unnecessary verbiage. The terse approach would also provide more room for the text and it would avoid text wrapping. I'm thinking along the lines of large magnifications for visually impaired individuals or screen shares where the text needs to be larger.

[timsuchanek]

Thanks for sharing that perspective, @n1ru4l, I appreciate that.

• For the pluralization - I'm absolutely fine with moving to singular. In fact, it was my first reaction as well, when I saw the design 😄
• For docs and builder/explorer in one view - Yes, I agree that we'll just need to build it and then see how it feels to know if it actually works out. It's a fairly bold move after all but I believe it's worth trying out.

[iftkharhussain]

Hi guys, I am a beginner can you please help me with how to install the new Graphiql with design v2? it looks very excellent I want to test it.

[nkuehn]

Thumbs up for making the explorer interaction a first class citizen. It's extraordinarily productive and allows to concentrate even better on the query to build beyond the syntax.

Integrating documentation is consequential - having two identical browseable and searchable tree structures in the same UI can be unnecessary mental load and a lot of extra clicks. The Figma screens are beautiful but the sample API is very "happy path". Here's some ideas for UX edge cases:

• Arbitrarily expanding / collapsing / searching the explorer tree to find certain documentation without impacting the current query
• Very long description texts
• description texts with arbitrary markdown. The spec does not constrain commonmark, so you need to handle H1s, images and code blocks etc.
• @deprecated fields (combined with other attributes or complexities)

[timsuchanek]

Nice those are great edge cases to keep in mind! We want to make the descriptions collapsable, so that should scale.
Will look into the other edge cases as well!

[FluorescentHallucinogen]

See also this thread: OneGraph/graphiql-explorer#10. It contains a lot of ideas. 😉

[timsuchanek]

Thanks @FluorescentHallucinogen! Yes, we've most certainly had a look into that thread. Indeed a lot of great ideas in there!

[jord1e]

Hey tim, these designs look amazing! I have a few questions

Search

Wouldn't it be a better idea to overlay the search bar over the types instead of above the types?

I presume the 'Query' section will be jumping up and down whilst you are typing in the current design, or am I wrong?

Error indicator

Insomnia has error indicators in the sidebar (little red dots). These are definitely useful - especially on large operations, maybe it is an idea to add them?

N more arguments

How does this work and what is the rationale behind it?

Docs in inline editor

How would we access the docs in the inline editor?

Whole schema viewer

Apollo Sandbox has this amazing whole schema introspection result viewer, it includes a download button for the raw SDL and JSON results. Currently we need to fire up a CLI and introspect to get the SDL, but a button would be great. The viewer would be an added bonus

Expansion chevrons

Insomnia and Apollo Sandbox have little chevrons to expand/de-expand(?) the operation and result, will we have these in v2?

[acao]

Great questions @jord1e !

A few of these will be solved by monaco-editor settings that can be set by default and user controlled:

have you seen our monaco-graphql example?

1. error indicators

monaco behaves like this by default when there are validation errors, with the indicator on the right side. the user can enable or disable this at the `monaco-editor` level. we can look into whether other types of error indicators are supported via monaco-editor

2. docs in the inline editor

you can currently access them in graphiql and monaco-graphql by hovering on a type which in graphiql on click will navigate to the correct docs entry. It also works with autocomplete. User provided markdown is rendered as well. currently they show documentation and inline `Type.field(arg: Type)` annotation that we will add hrefs to like in `codemirror-graphql`. eventually there will be jump to definitions support added

3. expansion chevrons are already possible with monaco-editor

[timsuchanek]

Thanks @jord1e and @acao!

Wouldn't it be a better idea to overlay the search bar over the types instead of above the types?
I presume the 'Query' section will be jumping up and down whilst you are typing in the current design, or am I wrong?

Yes, the search will probably overlay over the types. There are two states for the search here: One in the normal tree view (query builder) and the other one in the types detail view. In both cases I'll expect the search to overlay them. We'll however experiment and then see what works best.

Insomnia has error indicators in the sidebar (little red dots). These are definitely useful - especially on large operations, maybe it is an idea to add them?

I think such an indicator should be feasible!

Whole schema viewer

Yes! We have enough space for extensible points in the new design where we can provide this. See the various icon bars.

N more arguments
How does this work and what is the rationale behind it?

We show the required arguments by default and all other arguments are then behind the "n more arguments".

[mshaaban0]

This looks very nice.

A couple of notes on accessibility ♿ that would be nice to take care of:

• Minimum color contrast i.e. (grey on grey), checkout Contrast Figma Plugin
• Color blindness tests, checkout https://cielab.io/
• Standalone icons must have text or tooltips

I'll be happy to provide code reviews with more deep dive tests with keyboard navigation and screen readers during implementation. Good luck 🤞🏼

[acao]

@mshaaban0 We are keeping accessibility at the forefront of our effort! Thank you this is a wonderful offer!

Do you mind if I ask for reviews as we iterate towards this?

For example, we are introducing tabs here, and I've been trying to make sure that tab, tablist and tabpanel are respected, and proper labelledby/id matching, etc. I think the only thing left just with this tabs implementation is a roving tabindex strategy, at least according to what I can tell from the wai-aria spec & example for tabs

#2197

note that codemirror 5 is not great with accessibility for the editor elements themselves, but that will change with both monaco-editor and codemirror 6.

[timsuchanek]

Thanks @mshaaban0! We'll definitely keep that in mind as @acao mentioned!

[lancethomas1]

Hi. This is looking incredible! Love the thought and intentionality you guys have put into this. It's much needed and well over due.

I'm curious as to what the interactions will look like for defining an operation name, adding multiple operations, setting field aliases and using fragments? Thanks!

[timsuchanek]

Good questions @lancethomas1.
My naive answer for now would be: Do it in the editor, but we'll see how we can cover all those cases in the sidebar!

[acao]

@lancethomas1 our goal would be parity with graphiql explorer in those regards, as our goal is to essentially adopt that project

[timsuchanek]

Hey everyone, we have some updates!
We've shown this design now to many people from the GraphQL community and will also review this in the main GraphQL WG on April 7th.

With the feedback we got, we suggest a few changes from our initial design:

• Theming: To make this more GraphQL-native, we switched the green play button to the GraphQL pink and adjusted all colors around that
• Minimalism: One of the design goals is, that when I open GraphiQL as a user, I only see what I need to see. The variable input is only needed when I actually use variables in my query. Because of that, we will hide the variable input until needed. We will go with a similar approach for headers, stay tuned on that. (just to avoid confusion - this is not visible in the screenshot yet)
• Sidebar vs fullscreen switches: We want to make it easy to extend GraphiQL. One area that needs to be extensible is the sidebar: Currently featuring the docs explorer including query builder, but also allowing custom plugins/views. We changed the design here to be similar to VSCode: We now have icons on the left, which you can toggle and will change the sidebar. Now there will be plugins that will change the whole screen, for example a GraphQL visualizer or an AST viewer. To keep the behavior consistent, we don't want those to be switchable from the side icons. Instead, as they would have a whole different kind of behavior by replacing the whole view, we suggest a different place to toggle that. We suggest locating it in the top left of the editor, where you can switch the modes:

This is the new light theme in the full view:

And the new dark theme in the full view:

We're curious to hear your opinions on this!
Feel free to join the GraphQL WG meeting on April 7th if you want to join the discussion in person!.

[Ambro17]

Will there be a way to expand a field description?
Sometimes they include examples or alternatives for deprecated fields and the screenshot doesn't seem to show that much space compared with the current right sidebar of graphiql that can show the field and its description using all vertical space

[timsuchanek]

Absolutely! We might even show the full description by default - that's something we still need to play around with

[tot-ra]

I somewhat dislike these condensed property descriptions, because

1. while in the list, they are not readable and only pollute visual space
2. they don't have enough space to fit relatively long descriptions
3. its not clear how long descriptions may look like. As I understand, the format supports markdown, so I'm curious if it can fit tables there or images.

For example, this is how I used markdown for mutation input descriptions before.. so I'd expect it to be the same or better in new version

[timsuchanek]

That's really good feedback, thank you. I totally understand your point. We should experiment with that - in that the design is quite flexible.
I can definitely see the expanded versions as the default as well.
The reason we added the condense version, is that the descriptions can even be full markdown. In some cases it would make sense to limit that and I'd expect more people to have these rich descriptions in the future.

[tot-ra]

About editor tools / buttons - I'm not sure what is second icon representing? Formatting / cleanup? Copy?
Copying query & response would be nice. Optionally - replacing all of the variables with their values when its copied.

[timsuchanek]

That's the prettier button. We should also have a tooltip on hover saying what it is.

[ItzaMi]

Agree with @tot-ra !
As a person coming into a project, I will have to traverse several clicks to get to know the variable and their description. While not fundamental, my feeling is that the context should never be hidden by default.
On the other hand, I can see how the condensed view might be beneficial, and it might be visually polluting to have all the descriptions open with this new UI.

I'm wondering how useful could be to have a modal appear with all the info related to the query

[acao]

Currently in graphiql you can command/ctrl click any variable type def, field or argument to navigate to the docs item for it!

[simmerer]

I love where this is headed! Great aesthetic choices.

I have some comments & ideas around the Headers pane.

Based on recent experience with our users, it's too easy to overlook the Headers pane (and its contents) when it's essentially a tab behind the Variables pane. Headers are sometimes an important piece of context for a given request being tested via GraphiQL, and it's vital that a) it's obvious at a glance that something non-default is present there, and b) any headers are included in the URL when sharing a link for someone else to reproduce from their browser.

The alternate UI you've proposed (where Headers are moved into the Settings modal) looks nice, and the "Add Header" button + list style is very promising! However, moving the Headers functionality into Settings feels like it's divorcing the headers information from the rest of the operation, and suggests that any headers present would not be included when sharing a repro link with another user.

Here's two variations on a design that keeps both Variables and Headers panes at the bottom of the Editor, and provides better discoverability, even when they're collapsed. (Please forgive the slight font change, as I didn't have TT Commons Pro handy.)

I also realize I'm late to the discussion, and that this mockup could be viewed as veering away from the "minimalism" goal :)

Cropped, here's the key bits:

Initial state: vertically stacked

Values entered:

Alternate UI for Headers key/value pairs:

Non-empty panes collapsed:

[timsuchanek]

Thanks @simmerer, this looks amazing!
We'll probably go with a mix of the designs. One goal is to keep as much vertical space as possible, which would be a challenge with the design you suggested.
However, we can still make headers more visible and a suggestion I love is the (1) number indicator. We'll take that into account in the final design!

[simmerer]

I definitely felt the challenge of vertical space conservation! I think the indicator will solve most of the issue, now that I'm looking at it again - glad to hear idea this might help!

[all2pie]

Some great features that should be added:

• Nested folder support for better organization of Queries
• Shared headers across collection
• Environment variables

[jonathanawesome]

New design looks great! I see that TT Commons is used extensively in the Figma file, which is surprising because it's not open source. While I think TT Commons is a fantastic font, I can't identify a compatible license on the TypeType site.

[stonexer]

Hey, I love the new design, especially the docs explorer!

I can't wait to try it out, so I've simply developed a rough version (10% of the full functionality, 10x bugs :) ) based on the new design. It would be nice to try a little and find some more new ideas!

Online demo: https://stonexer.github.io/graphiql-picker/
Source code: https://github.com/stonexer/graphiql-picker

[acao]

Beautiful work! Thanks for doing this! That’s a great idea, prototyping like this will really help us explore this UX, agreed!

[julianbauer]

Absolutely amazing to see this alive as a protoype! And thanks for the kudos!

[timsuchanek]

Wow this is awesome!!

[jonathanawesome]

Inspired by the work of @stonexer, and in the interest of getting the ambitious plans into an interface for all of us to to play with, I've a prototype that includes the new monaco bits. Built with Ladle, the prototype is focused on the reference but the option to build out a full component library as part of the GraphiQL design update is there.

Reference
Ladle root

Source: https://github.com/jonathanawesome/graphiql-prototype

[stonexer]

The prototype looks amazing!

[jonathanawesome]

Hey folks! Lots of fun things to see and discuss in the latest version of the prototype. I encourage you to just go right now and play around with it.

While you're exploring the prototype please understand that I've taken lots of liberties in terms of design and that it's probably going to break on you at some point. When it does, let me know.

So, some notes about the prototype:

• Pathfinder
  I was getting confused with all of the docs/explorer/docs-with-explorer chatter so, in the prototype, the thing you use to build queries visually is called Pathfinder. I've attempted to address some of the earlier, and very valid, concerns about this UI by creating options for moving around descriptions. Clicking on the ellipsis icon shows the following UI where you're able to set the description placement/visibility and change the visibility of type pills (again, liberties):

• Schema Selector "Plugin"
  The default schema in the prototype is the test schema from from the GraphiQL repo...thank you @thomasheyenbrock. It's meant for testing Pathfinder and will give you an alert() if you try to run an operation. Clicking on the GraphQL icon in the sidebar will bring up a dialog that allows for the selection of two well-known and publicly-available apis that you can run operations against.

• Variables
  I was having a number of issues with monaco that made the variable editor unstable, so I built up a previously-designed UI that didn't involve monaco and I really like it. There's design work to do around it, as I've taken liberties, but it's pretty solid. Try playing around with the test schema and the hasArgs root field....

• Local dev API
  In the repo, there's a Yoga/Express/Prisma server that's meant to be spec-compliant. I haven't had time to flesh it out, or write documentation, but if you know the stack, have docker installed, and can read a package.json you should be able to get it up and running. I'll publish a new readme for the repo ASAP that includes getting the local api up and running.

Happy to help anyone get involved with the prototype by having calls or peer programming, and you can always ping me on discord.

[julianbauer]

This is amazing! Really great work on the prototype. I like the option to have different modes for descriptions in the docs explorer. The liberties you've taken in terms of variables design are a great direction too, little I would do differently. I'll put some design input and feedback together, but this looks really solid already

[jonathanawesome]

Hey all! After a couple of months of work I believe the prototype I've been working on is ready to get hammered and validated.

It's been a few months since the early momentum and I'm not sure how many folks are subscribed to this issue, so I'm going to do something gross and @ everyone that commented earlier this year with the hope that they're still into helping to figure this thing out.

No one is safe from my @'s...so, @timsuchanek, @n1ru4l , @EdwinJackson, @nkuehn, @FluorescentHallucinogen, @jord1e, @acao, @mshaaban0, @lancethomas1, @Ambro17, @tot-ra, @ItzaMi, @simmerer, @all2pie, @stonexer...your earlier opinions are valid and I'm asking for your help to further explore this new design.

The prototype is running here. I'm expecting to revise and revalidate this prototype very often so please join us on the discord channel to continue the conversation around the prototype.

[jord1e]

hey @jonathanawesome this looks awesome! I found a lot of tiny things in the prototype, those are listed below. The new design looks amazing and way more pleasant then the old one, it will definitely help the adoption of GraphQL! Maybe I can contribute some fixes for a couple of them, but I am not a JS/TS/web expert at all and have limited time (as do you, thanks a lot).

On Firefox, the removal X in the Settings dialogue is incorrectly aligned (it is correct on Chrome):

The Schema Selector and Settings buttons do not have tooltips:

Hovering over the [more info] the the schema selector actually highlights the entire line, including selector bullet. This is kind of unintuitive since it opens a completely new tab. Maybe an 'external link' icon could be added inside the brackets (https://fontawesome.com/icons/up-right-from-square?s=solid) -

? or instead of [more info] it could be [view schema]

Clicking Use this schema without a URL currently does not give meaningful feedback

Bug in documentation viewer when GraphiQL just loaded? A ghost documentation pill? After reloading the page this was gone - but still weird

• The documentation viewer stays on the last schema's documentation when you select an invalid schema in the schema switcher dialogue.

The "not backed by a server" is quite sudden. Could it be incorporated in the schema switcher? Maybe a URL under the schema name?

I get a TypeError: n is null when opening a (not previously opened?) sub menu in the pathfinder:

The fading in the docs viewer can cut off descriptions:

The variable EasyVars selector list seems to randomly sort and reorder when clicking, it is kind of unsettling haha:

The parenthesis () are almost invisible on the white backgound:

The contrast on the EasyVars list removal buttons is not great (same problem as above):

Maybe a tooltip for the + tab add button would be nice, this is especially true on first load when the button is right next to the GraphiQL 'logo':

• The EasyVars tab stays on a operation's variables after the page has been fully reloaded and the operation is gone.

When there is only one tab, EasyVars will just say Tab 1:

The hitbox for the initial 'new tab' 'button' is super small, and you can quickly smash the button that opens a new tab with the github page by accident:

Weird error in the variables editor?

• You cannot rename tabs currently

When you have to many tabs it 'breaks':

The Type Pills options does not seem to do anything:

The 'Copy' button from the old UI is gone 😢:

[jonathanawesome]

Wow, this is great feedback! Thanks for the thorough review, I've made most of your comments into issues in the repo and will be tackling the low hanging fruit today. Getting these little bits fixed up will allow everyone to focus on the primary goal of the prototype, which is hammering on the Pathfinder/editor interactions.

[AndrewIngram]

One thing i'd quite like to see is some kind of visual aid to highlight the relationship between fields in the query and the payload. Quick mockup:

So in this, i've clicked on the of the lines in the payload, the second "title" row, indicated by the darker bg and visible border, and the other lines that relate to the same query line have been highlighted, along with the query line itself. The opposite would also happen -- selecting a line in the query would highlight the appropriate lines in the payload.

I envisage a similar behaviour with error paths when there's an error payload

(bonus point for a lovely bezier curve linking the highlighted payload and query lines)

[jonathanawesome]

This is a great suggestion and one that I personally haven't seen before. Anyone aware of an existing/prior-art example of this interaction?

[orta]

Not in the GraphQL space, but vscode would highlight the same variable when you select it and I've played with similar concepts in the TypeScrpt playgound with extensions. This is a great pattern, and a clever idea.

[AndrewIngram]

One thing that feels a little strange is when using the Pathfinder for input types (as opposed to a scalar)

I'd personally never construct a document like this, rather than a variable for each individual field in the input type, i'd have a single variable holding the overall type.

I also completely failed to construct an update or delete mutation with the SpaceX API

[jonathanawesome]

Excellent notes...thank you for trying out the Pathfinder feature in the prototype!

A clarifying point re: the SpaceX API. The mutations and subscriptions (all of the user*-related fields, actually) on the demo SpaceX schema are bolted into the server...they're separate from the actual SpaceX api that's being accessed to fulfill query operations. I'm not confident that these add-ons reflect real-world usage, but they are valid and the Pathfinder plugin needs to handle them better.

We need additional design effort around input types for the new visual query builder (Pathfinder). In your screenshot, for the insert_mutations field, the objects input type should accept an array of objects...this isn't handled at all in the current Pathfinder. It's a known issue that's been waiting for me, or anyone else, to get around to designing and writing a solution.

I'd personally never construct a document like this, rather than a variable for each individual field in the input type, i'd have a single variable holding the overall type.

OneGraph's Explorer handles this well. The default is variable-per-field, but they provide a button on hover to extract the currently-selected fields (all required fields are selected by default) into a single variable. Do you have thoughts on how this interaction could work?

[FluorescentHallucinogen]

I've visualized refactoring (extracting) any input fields to variables a few years ago in OneGraph/graphiql-explorer#10 (comment). This is an equivalent of OneGraph/graphiql-explorer#10 (comment).

The output fields can be refactored (extracted) to fragments in a similar way. This is an equivalent of OneGraph/graphiql-explorer#10 (comment).

And here's a visualization of array support: OneGraph/graphiql-explorer#10 (comment) (that at the moment has not been implemented in either GraphiQL Explorer or Apollo Studio 🙈).

[AndrewIngram]

Having used the current incarnation of the released GraphiQL v2 for a few days now, I have thoughts. This originally started out as feedback about light mode colour contrast to add to #2676, but it quickly cascaded into discussing the design as a whole (though admittedly still from the perspective of light mode, since I never use dark mode).

Comment colour

First things first, the comment colour is very faint. This is especially noticeable on first load with the instructional comments, this is close to unreadable threshold for me, but definitely causes me eyestrain.

Nit: None of the buttons have hover states

Bracket-pair highlighting is almost imperceptible

General low contrast greys

This once is harder to explain. But this almost "striping" of low contrast greys is quite uncomfortable for me, it feels like it's always trying to get my attention, but causes similar eyestrain to the low contrast comment colour. The designer in me is trying to understand the rationale behind the entire "rounded box inner countainer" look, all it's really doing in my mind is creating additional UI noise (in contrast to the colour scheme which seems to be going for mimimalist) and using up a lot of screen real estate. It feels like there are conflicting design ideas going on -- you have the initially hidden tab bar aimed at conserving screen real estate, but then extremely airy and spacious curvy boxes undermining that.

Actually, looking back at the original designs, the greys were different, and there were some additional thin borders which seemed to provide some much needed edge contrast; were these changed intentionally?

Tabs

New tab button moves around based on whether there are existing tabs, not sure this is the right call. Also not sure that I really agree with the "hidden by default" decision; it saves a bit of space, but as mentioned before, that space can be reclaimed by tightening up some of the other design elements. It almost makes the tab feature as a whole less discoverable -- just a little plus button that next to the word "GraphiQL". On that note, I'm not really sure if we need the word GraphiQL there, does a user actually care? It's a surprising amount of space to give over to branding in a dev tool.

Variables / Headers

Mostly just contrast-related nits. The "active" tab state isn't particularly obvious, and the overall panel feels like it faded into the background a bit too much. Perhaps a background colour that's distinct from the query panel might help here?

Dark mode

As mentioned, I don't really use dark mode. But after taking a quick look, most of the contrast issues I have with light mode seem to also apply here. But as I tend to avoid dark modes for contrast/legibility reasons anyway, I don't feel as qualified to comment.

General thoughts

Overall, I think GraphiQL2 looks nice from a purely visual standpoint, along with some great functional changes. But I can't help but leave with the impression that the primary goal of the aesthetic changes was to look modern and minimalist, which seems to have been taken to mean a very muted colour palette + generously rounded corners. GraphiQL 1 looked a bit dated for sure, but some of the changes feel like change for change's sake rather than motivated by addressing particular issues.

[thomasheyenbrock]

Thanks for this elaborate feedback! 🙏

• I opened a draft PR that starts to address the color contrast issues, in particular the comment color, the matching brackets, and the "additional thin border" (a box-shadow around the query editor) you mentioned
• Hover styles for buttons have been added in add hover styles for buttons #2741
• I can't speak a lot to the design of tabs in v2 as I wasn't involved a lot in the design process here.
• The "GraphiQL" text has an additional purpose as the place where custom implementations can include their own logo. This has already been the case in v1 and apart from the placement it didn't change in v2.

[FluorescentHallucinogen]

I don't like the current proposed GraphiQL Explorer design for one reason: too much visual noise.

As I wrote in OneGraph/graphiql-explorer#10 (comment), combining operation building and docs viewing is not a good idea, because they solve different problems:

• Docs displays some schema things like directives, interface details (like "implemented by" and "required by"), union and type extension (extend type ...) details that don't matter alone out of query building context.

• Types and long descriptions next to field names are not necessary for building operations.

As proposed in OneGraph/graphiql-explorer#10 (comment), types and descriptions can be displayed on field hover:

User can open detailed docs for the field right from the links in the field hover popup.

Another option would be to display a hover icon next to each field to open the docs, as proposed in OneGraph/graphiql-explorer#10 (comment):

BTW, this requires the (deep) integration between GraphiQL Explorer and GraphiQL Docs.

I don't see any point in the "Show arguments" UI element.

As proposed in OneGraph/graphiql-explorer#10 (comment), arguments can be expanded/collapsed by just clicking on them:

I don't see any point in the "N more arguments" UI element.

Why is only the first argument shown and the rest hidden? A huge number of arguments is very rare.

[klippx]

I love this idea. The visual noise in the proposal is terrible. But I do see the value in connecting schema and documentation.

So, the tooltip on hover is an excellent compromise, the docs are still there but tucked away beneath a tooltip.

As an analogy: You don't see the docs for a JSDOC code commented method printed out in-line in your code editor when you use that method or types (we all would hate to see that right), but if you mouse hover the method then you see the docs for it.

[berkowitze]

Hey the discord invite link seems broken or the server was deleted or something - is there an up-to-date link?

[thomasheyenbrock]

Hey @berkowitze, here's an invite link that does not expire: https://discord.gg/NkBEqJvz

[klippx]

That's invalid as of today at least, please post a new one @thomasheyenbrock

[thomasheyenbrock]

https://discord.gg/tnkGYN6aCp

[klippx]

What is the progress on the prototype in terms of schema documentation? For those of us not in the discord.

I am especially interested in the schema explorer with merged documentation. This is one of the best improvements we are looking forward to. Keeping schema reference and schema explorer separate in 2.0 would be a really poor decision, but it looks like that in the prototype today 😢

No inline documentation in the schema explorer

In the design you have field documentation as inline, to the right, singe line (truncated), but I don't see that in the prototype, instead I have to click in to the "View Quick Docs" to see the docs.

Is this being worked on?

Poor view of documentation in schema reference

IDK if you even want to keep "schema reference" (as we would rather see it merged with schema explorer) but IF you are planning to keep it then it looks a bit lacking in the prototype: All docs are hidden behind clicks here as well. You are not even showing the different query description when I click "Query", it is just a list of root queries withoutr any docs. This give no extra oomph compared to schema explorer 1.0 as it looks right now.

Schema explorer docs

"Moving Docs and Docs explorer into one. "

YES. PLEASE. This is the revolution we need.

Now, I know a lot of people already whined and mentioned "visual noise" but who are we catering to? Super users / developers that already know the schema - or those who don't and should adopt and love the GraphQL API we provide at company X? Not everyone is a rockstar dev, some people in the company still work in "inferior" languages and are rewriting REST code to GraphQL and have no familiarity at all with the technology. And they might even hate GraphQL.

I would hate to see all this whining and pushback from community to be stopping the best idea ever.

But what we see in the prototype today is an explorer, where in order to see docs you have to click on each item, and then click close, while keeping a growing the context inside your head. Is this a nice experience to offer for a user trying to grok the schema? This is over the top minimalistic and it does not do well in terms of guidance or help. Isn't this so far just a reboot of GraphiQL Explorer with an extra small "docs" button for each field?

"Moving Docs and Docs explorer into one. "

So far the prototype sadly fails to deliver on the promise.

But the good thing is that YOU don't have to make a decision, as everyone could have it their way. With a new setting, you can let the user decide what the experience should be. Lets take another look at the different user setting modes we could have in GraphiQL 2.0:

• Mode A: No docs. Great for those that want no visual noise. ✅ - aka "GraphiQL Explorer 1.0 mode"
• Mode B: Inline truncated. Great for those somewhat familiar and just needs small cues to navigate. Sort of the compromised version you have in the Figma design. ✅ - aka "GraphiQL Explorer 2.0 mode"
• Mode C: Full docs above each operation/field. Great for complete newbies who just started at the company and has no idea about the schema and dont even know what they are looking for. ✅ - aka "GraphiQL Explorer 2.1 firehose docs mode"

The cool thing with Mode C here is e.g.

• I can see the full documentation in-line in the explorer tree above each query.
• Docs can be folded by default and have an "expand all" button - or the other way around, expanded by default and need to be folded as you scroll around.
• The user can explore the schema by scrolling and reading in a single location without need to click (save for folding, if I want to).
• The user can be allowed to fold and/or expand docs for each operation/field as he/she decides about the relevance related to the current thing they want to do
• The explorer is now a tool (with state) to browse and find queries they need and they can context switch and resume the task without the manual context building/memory leaks inside their head.

WDYT?

[acao]

@jonathanawesome has been working on this already!