Redesign GraphQL.org's homepage

[Urigo]

Find the latest designs here

Find our new messaging for GraphQL in order to put it on the main homepage

Current thinking:

Add to the homepage not only what GraphQL is but also its value proposition.

• Main hero section - "The Query Language for Modern APIs"
  • Add 3 main value propositions:
    • The best app user experience
    • Security and stability
    • Efficient distributed development
• Second section - Used at scale by the world's leading companies (logos....)
• 3rd section - what is GraphQL
  • similar to what we have today
  • Describe your data, Ask for what you want, Get predictable results
  • Link to how it works on another page
• 4th section - why businesses choose GraphQL
  • 3 value propositions
    • The best user experience (to show the unique benefits of GraphQL on client applications)
    • Security and stability (show the unique benefits of GraphQL in managing API changes, strict schema and automated security features)
    • Efficient distributed development (To show the benefits of teams taking different parts of the schema while using automated tools to sync their work into a single GraphQL schema)
• 5th section - The 5 pillars of GraphQL
• 6th section - Data Colocation - demonstrating GraphQL's unique ability to manage frontend data at scale
• 7th section - is GraphQL right for me
  • A list of use cases and if GraphQL is the right choice
  • Possible use cases:
    • A large backend with many services
    • A mobile app
    • A frontend heavy app with advanced UI and user needs
    • An app with real time updates
    • A simple full stack Typescript app
    • Something about AI
• 8th section - testimonials
  • From (hopefully high rank individuals companies from Meta, Netflix, booking.com, AirBnB, GitHub and others)
• 9th - community section - leads to all our community resources

[saihaj]

I would switch order of 2&3 and 5 & 6.

[JoviDeCroock]

Something I have missed in almost every value proposition section about GraphQL ever are the pillars of GraphQL. These really paint a good picture about expectations and make clear that GraphQL focusses on the product, it's not just any query language, it's a query language for your product, regardless what medium that product runs on.

[doc-jones]

First, what I like about this outline is the thought that has gone into it and how useful it is for discussion. There's a good balance between educational content and marketing/promotion of GraphQL.

I, also, find that I have opinions. :-)

I would delete Section 5, because most decisions that are made of what technology to use aren't based upon this technology versus that technology for building APIs. From what I've observed across teams and customers is that often a technology is selected because the team that implemented it wanted to use it. They may have personal opinions about the ease of adoption for REST, or they have never deployed GraphQL before, so choose it for that reason (i.e., new shiny thing). Larger enterprises most frequently have all available technologies represented on their network as various teams across many years have made different choices. Rather than a chart of competition between API styles, I would love to see information on how API styles can be used together or complimentary to one another. I think it is important for GraphQL to be more forward thinking as the realities and complexities of modern data requirements have changed.

Would it be possible to update graphql.org in stages? This thought occurs to me because, if we were to collect information from across the community and more broadly across adopters representing different industries, corporate sizes and uses cases, this information would inform what would be most helpful to add in sections of the website. There are new developments and uses for GraphQL developing as knowledge graphs become a critical piece of systems using AI/LLMs particularly for large enterprises. GraphQL is being implemented and integrated in new and complimentary ways across blockchain systems. New protocols are being developed to enable communication between AI agents and APIs. Questions to be answered include how well does the GraphQL spec and tools support all of these new uses. Perhaps? The data can direct us.

I love @martinbonnin 's discussion of building a survey #30 . A survey that is thoughtfully constructed and well promoted would give us not only a excellent way to engage and broaden exposure of the community to more adopters, but also create a wealth of content to clip and share across all GraphQL Foundation channels including the website over many months. Maybe even to new channels.

Section 6 and 7 we might consider combining these, but only after gathering data from a large survey effort and a collection of adopter case studies. More about this soon, I hope.

Section 8 is chef's kiss - perfection!

[Urigo]

@JoviDeCroock Love it!
where would you position these and what would you write about them?
Can you add this to the proposal above?

@doc-jones about section 5 - I knew its going to be controversial :)
I agree with your assessment on why technology is selected in teams.
The reason I wanted to add this to the discuss is that currently these table are everywhere and they are being written in a way that doesn't serve us justice.
This is an opportunity to add our perspective into that conversation and do it in the way that you described - not as a competition but to give more context then the alternative tables out there currently provide

About the stages - of course - the website is always a moving and evolving project.
I would always favor moving forward with what we know while gathering more information on the new use cases you've mentioned. Once we'll get that information, we can and should add it to the website!

Excited on making progress here!

P.S.
In a similar fashion to the "Bias towards action" and moving forward with what we currently know, and the fact that the website is always an ongoing project, I would also want us to always think if the proposed change is better then what we have today, not if its perfect

[martinbonnin]

Can we have a big "TRY IT OUT" call to action with a GraphiQL embed on the main page? I know we have it in other pages but:

• Some people never leave the home page
• Took me 8 years to realize that those elements were interactive. For some reason, I always assumed they were non-interactive.
• Everyone I talk to loves GraphiQL. Sounds like a big selling point for GraphQL.

[benjie]

I'd love to see that big "try it out" somehow integrated with the component based model of rendering, demonstrating clearly the value of fragments. I think too many people sleep on fragments, we don't do a good job of selling them up front, and too many people think they need to select everything manually and build massive "mega fragments" that all their different components use even though each component may only need a couple of the fields.

[andrewmcgivery]

5th section - comparison table - compare to other protocols (REST with OpenAPI/JSON schema, gRPC)

Dropping in just to say I'd love for this to have some nuance around GraphQL doesn't necessarily replace your other APIs (REST, GRPC, etc) but rather can be a great way to augment and magnify the investments you've made into those APIs.

So much of the problematic "debates" and GraphQL-hate often stems from this "comparison" of which one is "better" when in reality where we see the most success in large enterprises adopting GraphQL is to use GraphQL as the "middle" layer between the UI and service layer... using them together instead of pitting them against each other.

In my opinion, this message of "better together" is a much more productive, de-escalating, and winning message for GraphQL than "why is GraphQL better than REST".

This talk from API World is a great discussion on this exact topic: https://www.youtube.com/watch?v=5DVi99KPALo

[Urigo]

@benjie do you have an idea on how to best demonstrate these points visually and textually?
#21 (comment)
I'm thinking maybe we could use ideas from these two talks:

1. https://youtu.be/9sc8Pyc51uU?si=xKBfZFgDblRsmHTM
2. https://youtu.be/WxPtYJRjLL0?si=81oT3W7byWvNi4qx

[Urigo]

@andrewmcgivery wow, that's one of the best talks I've seen, thank you so much for sharing!

I very much agree with everything you said in your comment and the messages in the video.
I would love your help thinking on how we can integrate these messages into the new home page!

Looking at the table, let's say we change the format of it, but keep the point there, some are related also to the points from the talk, how do we present them in the best way?

Some thoughts on replacing section 6, I wrote while watching the talk:

1. The focus on the middle layer and how to manage it at scale. I would love to visualize it on the main page. I think its related to two of the three main value propositions we want to talk about - Security and stability and Efficient distributed development. I'm thinking where could we use similar visualizations from the talk on the main page

Taking points from the table, that we might drop or integrate as they are related to this part:

• Distributing development of services across teams
• API usage reporting
• Managing versioning and changes of the API

2. The other points from the table that are not covered by the talk, do we want to include them or maybe some of them already are covered by other sections:

• Strict schema
• Managing UI data requirements in components
• Consumers and clients ease of use
• Performance
• Ecosystem tools
• Something about AI

[erikwrede]

Expanding on @benjie's comment

I think too many people sleep on fragments, we don't do a good job of selling them up front, and too many people think they need to select everything manually and build massive "mega fragments" that all their different components use even though each component may only need a couple of the fields.

In my opinion, we need to motivate fragment use differently. Many newcomers to GraphQL are not aware of the best practice of UI-Component-driven queries. We don't do a good job at all of selling the synergies between GraphQL and the actual frontend hierarchy. Otherwise, we would not see so many people expecting GraphQL to just be a database-like query language for API queries, or implementations using GraphQL like a rest API - heavily abstracted away from the view and fetches split up into many queries. From a very critical perspective, the learn page reads like an introduction to SQL, not like the introduction to a powerful tool that can revolutionize the way you define, consume and utilize APIs to build next-generation apps.

Part of this is due to our strive to be as vendor- & tech-neutral on the main pages selling GraphQL. The aforementioned synergies are mainly enabled by tooling, no matter if open-source or by vendors. We are going to have a hard time showing the intuition of fragment-driven queries if we abstract away from the hands-on intuitiveness that a concrete example brings.

Is this complete abstraction away from implementation a point we could put up for discussion? I'd personally favor a well-balanced approach that sprinkles concrete technology examples into the page, while staying neutral in that we don't unfairly position any tooling over other options.

This is mainly something to discuss for the other subpages, but it could very-well affect small portions of our landing page. I'd be curious to hear your opinions on this intentionally challenging take 🙂

[Urigo]

@erikwrede I think you are right and I also think this today is a generally agreed upon idea by the leaders of the community

I don't think that the reason its not highlighted right now is because of vendor- & tech-neutral thing..
All vendors and popular clients today support these patterns today

I think the main reason is just that nobody did it yet :)

So let's split that into two things:

1. What do we want to say about it on the main page - can you suggest something concrete to the structure on the first comment that could bring these ideas more? For me, the sections where I wrote The best app user experience, some of the 5 pillars, Managing UI data requirements in components, A frontend heavy app with advanced UI and user needs - where exactly added to highlight that quality of GraphQL that no other API spec has
2. Bringing more of that content into the rest of the website (tutorial, docs, etc). For that let's open a new issue

[benjie]

I don't think we have to be particularly vendor-specific in this - React, Vue, Angular, SwiftUI/UIKit and Jetpack Compose (I think?) are all component-based systems that would pair nicely with fragments. I think we can show component-based UI and GraphQL fragments without needing to be vendor specific at all; but I'm afraid I don't have the design skills to actually pull something like that off.

[erikwrede]

Thanks for clarifying @Urigo 😊

Regarding

1. We could have an interactive view with a demo app on the left - hovering over each ui element reveals its fragment on the right, and a slogan like "Connect Components Seamlessly with GraphQL Fragments". I don't either have the design skills to pull this off, but we could ask some AI tool to try and draft it for us. Something like this, but in pretty (I did not check any components for correctness, just a sketch 100% ai generated): https://v0.dev/chat/graphql-fragment-demo-R2N7Q9Bq8aK?b=b_xpQLeHGAjRy or https://v0.dev/chat/fork-of-graphql-fragment-demo-GV1daBRhWEp?b=b_S53JTL1VB93
2. I'm writing up a separate issue. Will post later

[benjie]

@Urigo If we could boil down the key points in that first video (but modernised and not Relay-specific) into our homepage I think that'd be amazing! Honestly this diagram itself is quite effective at demonstrating the concept behind fragments:

I really like Erik's v0 mocks too, though if the fragments are concrete I'd want to see something representing the data from the fragments within the components too, to make it more real.

[erikwrede]

though if the fragments are concrete I'd want to see something representing the data from the fragments within the components too, to make it more real.

100%! The v0 mocks worked better than expected. Maybe we can create an evaluation prototype for the entire page for the next wg so everyone can give feedback on structure, layout and content and then work on a proper design that actually looks professional. Does anyone here have a v0 pro subscription, or a similar tool with unlimited access?

And going back to that video is an awesome idea.

[martinbonnin]

Just dropping by to say that AI demo looks neat 🤩 . And the Android reactive UI-framework is Jetpack Compose indeed (not to be confused with the Compose compiler).

Jetpack Compose shares a lot of similarities with React.

[Urigo]

Thank you so much everyone for bringing so many good ideas and feedback!

I'm happy to share that we have a first version of the new design, ready for your feedback!

A couple of notes:

1. As mentioned in the meeting - the next version of the website is not the final, we are aiming towards the next step, not the perfect place
2. Because of that, please split your feedback into two sections
   a. Comments that are a no-go - meaning, it is worse than the current graphql.org version
   b. Comments that are an improvement - meaning it is not worse then the current version, but should be better - these could go before or after the first version of the implementation
3. There are two sections on the figma design that has animations, try to click on them to see how they would behave
4. These are not the only animations, just the important and new ones. We will use the some of the nice animation that we already have on the current landing page

Here is the link to the prototype:
https://www.figma.com/proto/aPUvZDSxJfYDJtPd7GF2sB/GraphQL.org?page-id=10%3A13019&node-id=649-3367&viewport=-2607%2C336%2C0.13&t=eZKIRpRkrWRATgQb-9&scaling=scale-down&content-scaling=fixed&starting-point-node-id=649%3A3367&show-proto-sidebar=1

Here is a link to a video walkthrough by @ursusmeles (note that the Colocation animation was not ready there, so you'll just see the components without the animation - but on the prototype you can!):
https://www.loom.com/share/6849676aa9dd49e1b2da03851251e8f9?sid=464736dc-553a-40a8-9b7c-a40baf05c5d7

A link to the Figma file:
https://www.figma.com/design/aPUvZDSxJfYDJtPd7GF2sB/GraphQL.org?node-id=10-13019&t=C8TKNrzMeqojiA3C-1

[doc-jones]

2c. Suggestions for improvement

1. Place the Conf 2025 banner at the top of the page instead of the bottom
2. Replace the site title text.

Instead of defining GraphQL as merely a query language, I propose something like those below. Limiting the title to "a query language" places too much emphasis on FE only.

Designed for Composability. Powered by the Community.

GraphQL is more than a query language — it’s an ecosystem of open source tools and best practices for building and consuming APIs.

Alternatively...........

A Strongly Typed, Open Specification for Declarative APIs.

GraphQL enables precise, flexible data access — with a growing ecosystem of open tools for API producers and consumers.

.....more comments to come with more time available.

[jemgillam]

The "powered by community" section feels a little like an after thought at the moment. I hope there is room in the future to highlight our community initiatives like the local gatherings, the grants program and one day the ambassador program.

It feels like the main audience target is enterprise (with it being highlighted in a dark pink block unlike the rest of the page), is this the correct messaging?

[martinbonnin]

I love the new color scheme. It's both "new" and "old".

The pink ensures continuity and the green is very refreshing, very good balance IMO 🤩

My main feedback, (and I guess you saw me coming at this point 😄) is:

Can we replace the "learn more" button with a "try it now" button?

This page has plenty of links to learn more already, there's even a "learn" tab on top. Or viewers could just keep scrolling to learn more. But I really really want them to try GraphQL and let the technology speak for itself. I'm prepared to die on the "try it out button" hill!

[martinbonnin]

Do we have a timeline/rough goal? Like before/after GraphQL conf?

[benjie]

Where things are just text copy I'm generally not going to worry about feeding back on them since we can edit that ourselves later (one small example: "A GraphQL Query" outlines a schema, query and response; but the title makes it seem like the person writing the query must also "Describe your data" - this is easy to fix later by rewording the header).

Main feedback - I like it:

• The design feels clean and modern
• The fragments demo is great! (I have concerns about hover on mobile, but I'm sure you've got that covered!)
• I don't know what you call them, but I love the little section headers "▶ GRAPHQL ADVANTAGES" - they're cute but meaningful.
• Similarly the tags ("Productivity", "Consistency") - nice execution.
• I like the pixel-art icons for the pillars
• Animations are clear and smooth, not overwhelming
• Really well executed in general

---

2.a. Comments that are a no-go - meaning, it is worse than the current graphql.org version

• The hero didn't make sense to me until I saw it zoomed all the way out in the loom recording. Now I can see it's a hint of the GraphQL hexagraph, but previously it just looked like half the page was taken up by weird green and pink lines with no particular meaning... This is the one part of the design that I dislike, and it's the first thing you see.
• "A GraphQL query" section is too low IMO, giving developers something to look at that they can immediately grok at a glance is key, then they can carry that forward into their interpretation of the rest of the page. IMO it should be one of the first things they see.
• Currently the page positions GraphQL as solving the problems of the biggest companies (only):
  • "Used by the world's leading companies"
  • "What is GraphQL" implies it's only suitable if you have a lot of data sources
  • "A proven solution for Enterprise"
  • None of this is wrong or should be removed, but it very much is exclusive of the smaller players who have maybe a web app and a couple mobile apps, and just want a uniform, type-safe, and client-centric language to use to build their apps, one that can scale with them as they grow to having a more complex backend. I'd love to see messaging more along the lines of "Trusted by solo developers all the way up to the world's leading companies".

This third bullet I've included in 2.a because the current website does not have a strong bias towards size of adopter, but I don't think it'd take much to fix to remove that bias.

One last point, have we checked how well this design works for colourblind people?

2.b.

I think "Versionless" should be added as one of GraphQL's pillars.

[Urigo]

Thank you all for all of the valuable and deep feedback so far!

1. @doc-jones Place the Conf 2025 banner at the top of the page instead of the bottom - it is on the top no?
2. @doc-jones site title text - let's open a separate issue to decide on the main text where everyone can offer a suggestion? related also to @benjie's point about text changes
3. @jemgillam yes we could definitely improve the "powered by community". The idea is that the landing page section would anyway link to a full page with much detail, but also that landing page part could be improved. Do you have ideas what should we put into that specific section?
4. @jemgillam about Enterprise focus - you are right. one of the goals of the redesign was to think about the users we want to focus on and message according to their benefits. my thoughts on who should we target were based on this comment and the discussion we had on it on the meeting - Enterprise Companies and Fullstack Typescript apps.
5. @martinbonnin Can we replace the "learn more" button with a "try it now" button? I think this is a great idea! No need to die on the hill ;)
6. @martinbonnin Do we have a timeline/rough goal? Like before/after GraphQL conf? I want to deliver the first version asap. definitely before the conf. also potentially using the new design system to even improve the conf website design as well. Again, this is just the first version and we'll iterate on everything. Please share this with everyone you can so we can get as much feedback as possible!
7. @benjie good point about the text, we could easily change these at any point in time and even experiment
8. @benjie hero - good point, I agree the GraphQL Logo should be more obvious here, this is for people who are not GraphQL savvy and even I was missing it
9. @benjie Positioning of the "A GraphQL query" section - I don't think I have a strong opinion here. I like the fact we are giving a strong message to decision makers right away, but also developers would want to see the actual thing first. I'm good either way. Maybe others have more opinions or we'll just change it. another valuable point here is that if you're a dev and want to learn GraphQL or find something in the docs, you have plenty of subpages dedicated to you - the Learn subpage & Docs, for instance. So the homepage can be more high level to quickly establish that this is an important technology from the business perspective, too
10. @benjie position for big companies - similar to what I wrote on bullet 4 to @jemgillam - I'm happy that at least we have a type of person to focus on. I'm happy with the messaging for the larger companies. on the Fullstack Typescript apps that will have something powerful to also grow with, I was trying to think about the unique things GraphQL gives them on top of the popular solutions today. The main points I got were Product centric, Hierarchical and the data colocation section. also there is the section of "is GraphQL right for me" which I think would be a very powerful place to talk specifically to these users. saying all of that just to say - I agree with you :) what and where do you think we should add to target this group? I love the "Trusted by solo developers all the way up to the world's leading companies". Where should we place it? what else to add?
11. @benjie good point about colourblind people, will defer to @ursusmeles
12. About "Versionless" - would it scare some people? We need to really clarify it... We do have the "evolve without versions" section, which might cover it but also visualize it to show you can version if you want?

A general question - do you think we are in a state where we can also the designers to also start looking beyond the landing page and get designs for other sections?
Meaning, we will continue to debate and improve content and specific sections of the homepage, but overall design is ok to move forward to look at other pages of the website? (learn, community, FAQ, blog, conf)

[jemgillam]

@jemgillam yes we could definitely improve the "powered by community". The idea is that the landing page section would anyway link to a full page with much detail, but also that landing page part could be improved. Do you have ideas what should we put into that specific section?

I might find it difficult to convey my thoughts exactly as I am only a beginner when it comes to marketing and messaging.

With the heavy focus on enterprise in the body of the page, the "powered by community" section at the end feels a little like an after thought. Often, when seeing it added like that, what you find is that the open source part of the project is just there as a way to allow people to self host, but the company heavily up-sells you on a closed source cloud service.

This is not the feeling we should be conveying.

Is there a way to weave the idea that GraphQL is an open source, foundation backed project (with a community behind it) throughout the entire page?

For example, one of the concerns enterprise bring to us at Graphile is how sustainable is the project? How is it funded? If there's a way to allude to that higher up in the page that might not only address the question of sustainability, but also give the correct impression of the GraphQL community.

Edit: For example, the community and governance model are mentioned as one of the "selling points" of Async API:

Is this a useful advantage for the Enterprise audience? I think so, though I am not experienced enough to know for sure.

[Urigo]

yes I think I get your point, we have a superpower of a community and it needs to be shown!

Together with that, my thoughts here are that everyone that comes here are first and foremost looking for a solution to their problems, not necessarily a community
If they find a solution for their problem, then they'll think about the community, open source, sustainability and so on

So I think there is a lot to add about the community in the landing page, but I still thinking we should start with the problems GraphQL is solving

I would love to hear about possible solutions to this, I agree its important
I'll also spend more time and try looking at more websites to get ideas on this

Thank you @jemgillam !

[doc-jones]

Something I have missed in almost every value proposition section about GraphQL ever are the pillars of GraphQL. These really paint a good picture about expectations and make clear that GraphQL focusses on the product, it's not just any query language, it's a query language for your product, regardless what medium that product runs on.

This is important and should be reflected more prominently in the website, but it's not the whole reality of GraphQL adoption. GraphQL has become a critical piece of enterprise infra, namely as "the data layer" between internal services and public or partner clients: web apps, mobile apps, REST APIs, and so on. Both will be important to communicate to the global GraphQL community.

[doc-jones]

@Urigo We need to have a wg meeting to give more time to discuss and ask questions about some of the requirements and assumptions that have been made about the messaging and content on the website. Please see #75

[ursusmeles]

One last point, have we checked how well this design works for colourblind people?

Hey @benjie, great question! We checked the design across 6 different color vision deficiencies and all sections that could have been problematic turned out OK. See attached screenshot

[benjie]

Thanks for confirming, @ursusmeles!

[jemgillam]

Thank you @ursusmeles! Color blindness runs in my family so it's something I often pick up on too. I was worried about the pink/green contrast but it looks fine. So long as we aren't using only color to differentiate important information (eg while not using labels or symbols as well) then there's no issue at all

[Urigo]

The Guild were at a retreat so sorry for the lack of updates
I'm going to share the new versions based on your feedback in the next couple of days!

[Urigo]

ok I have some great updates to share, the design team has accomplished a lot by the time we were at the retreat:

1. They have updated the landing page design according to the feedback from all of you. You can find the latest version here
2. They also included a couple a options for the hero logo here
3. We have a new design for the GraphQL Conf website, according to the new design language! Please review and give comments:
   a. main conf page
   b. conf/resources page
   c. conf/code of conduct page
   d. conf/bring your team page
   e. conf/speakers page
   f. conf/single speaker page
   g. conf/session page
4. New design for GraphQL.org / Learn [aggregator]
5. New design for GraphQL.org / Learn / Learn GraphQL
6. New design for Learn / Best practices
7. Learn / FAQ

Next steps:

1. Please review all the new design and keep your great feedback coming!
2. The designers are now moving to the community pages of the website
3. First website PRs for the new design - As it is hard to track changes on Figma, I want to start creating PRs for the website and to get all of your feedback on the PRs themselves, would be much easier not to miss anything.
   As GraphQL Conf is getting closer, and we hope to get the new design in time for this year's conf, we'll send the first PRs to the conf website, I'll update here when we do.

[jemgillam]

The conference site feels really fresh, the green is growing on me! It's great to see this design applied to more pages, I have a better feel for it now.

I trust contrast has been checked, especially on the lime green sections with black text.

I don't think I have any other notes, aside from I like it!