Re-vamp Redwood splash-page

[alicelovescake]

This PR proposes a new variation on Redwood's splash page. In collaboration with @margalit, we designed and implemented:

• Basic design that welcomes user to Redwood
• Resource cards for doc, tutorial, contributing and blog example
• Latest version
• Social links
• Dark mode
• Mobile friendly

@margalit and I wanted to create this PR to get early feedback. Below are improvements we want to still work on:

• Gather feedback from RedwoodJS community
• Test usability on usabilityhub.com
• Accessibility review
• A way to automatically update version number

Lightmode (desktop + mobile)

Darkmode (desktop + mobile)

[dac09]

Looking really good @alicelovescake and @margalit - thanks for all the effort into this.

Just a headsup - for e2e tests to pass you'll need to modify this line here: https://github.com/redwoodjs/redwood/blob/main/tasks/e2e/cypress/integration/01-tutorial/tutorial.spec.js#L57 :)

[alicelovescake]

Looking really good @alicelovescake and @margalit - thanks for all the effort into this.

Just a headsup - for e2e tests to pass you'll need to modify this line here: https://github.com/redwoodjs/redwood/blob/main/tasks/e2e/cypress/integration/01-tutorial/tutorial.spec.js#L57 :)

Thanks for the heads up! Super helpful. Just made the change to the test.

[dac09]

Hey @alicelovescake!

A way to automatically update version number

Two options here:

A) You can query the current redwood version from the graphql api. The query is

query RedwoodVersion {
  redwood {
    version
  }
}

In this case, I would probably suggest just using fetch like this in the splash page:

    const response = await global.fetch(
      `${global.__REDWOOD__API_PROXY_PATH}/graphql`,
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
        },
        body: JSON.stringify({
          query:
            'query RedwoodVersion { redwood { version } }',
        }),
      }

B) Provide the version at build time
We can configure webpack to have a global variable present that gives you the version number. Not sure this is the right approach, considering all future builds would have this version there even when you don't have the splash page.

What do you think?

[margalit]

Test usability on usabilityhub.com

I ran two identical usability tests, one for the dark mode and one for the light mode with unique participants for each (ie. no-one saw both versions). I ordered 30 responses for each test from an international panel with the the main targeting option being intermediate/advanced technical use.

I was mainly trying to determine whether the messaging was clear and the interactive design elements on the page were obviously clickable for both dark and light mode variants. This was a very basic to check we hadn’t introduced any glaring usability blind spots. I followed up each question with two rating questions:

• How easy was that to find? (1: Difficult–5: Easy)
• How confident are you that your click is correct? (1: Not at confident–5: Very confident)

Where would you click to proceed?

Dark variant

• 60% of participants clicked the 'Generate a new page' link
• 20% of participants clicked the 'Tutorial card'
• 10% of participants clicked the 'Docs card'
• 10% of participants clicked elsewhere
• Average ease score of 4.14
• Average confidence score of 3.9

Light variant

• 59% of participants clicked the 'Generate a new page' link
• 21% of participants clicked the 'Tutorial card'
• 17% of participants clicked the 'Docs card'
• 3% of participants clicked elsewhere (okay that is 101% but try to ignore that for now)
• Average ease score of 4.17
• Average confidence score of 3.93

Where would you click to get help?

Dark variant

• 67% of participants clicked the 'Tutorial card'
• 20% of participants clicked the 'Docs card'
• 7% of participants clicked a social icon
• 7% of participants clicked elsewhere (okay that is 101% but try to ignore that for now)
• Average ease score of 3.63
• Average confidence score of 3.57

Light variant

• 72% of participants clicked the 'Tutorial card'
• 17% of participants clicked the 'Docs card'
• 10% of participants clicked a social icon
• Average ease score of 3.79
• Average confidence score of 3.45

Summary

We can expect real engineers to perform better than these participants since they lack lots of the context for this page. They also have the benefit of being able to try multiple links. Worth noting that in unmoderated tools like this you can always expect a small level of noise in the results so I’m not overly concerned about the mis-clicks. Also don't worry that many of these percentages don't add up to 100%, just a quirk of the reporting.

We may want to consider explicitly calling attention to where to find help since there wasn't a strong confidence in any of the choices presented. Where do we want people to go for help? Are we happy for people to head to the tutorial? If so might be worth updating this link to explicitly be the our first page since we can expect anyone seeing this screen to have performed the previous two steps.

Based on these finding I’m relatively confident that both the light and dark variants are good design solutions with most people proceeding from this screen by clicking the Generate a new page link.

[alicelovescake]

const response = await global.fetch(
      `${global.__REDWOOD__API_PROXY_PATH}/graphql`,
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
        },
        body: JSON.stringify({
          query:
            'query RedwoodVersion { redwood { version } }',
        }),
      }

Thanks @dac09 again for the useful tips! I implemented your approach 1 by querying the graphql api and it seems to work pretty well! It's in the latest commit. The version will now conditionally render when we are able to grab the latest release.

[dac09]

Ear marking this for v0.37. Top job on this!

[thedavidprice]

Wow, this is a great start! Thank you so much @alicelovescake and @margalit 🚀

Don't take my suggestions below as specific directions/to-do's. This is going to take more discussion with you two and others. Please let me know what you think. And I'm fine to wait until others chime in.

See Screenshot at Bottom with sections A) and B)

A)

This content is info that's based on state. Currently, it reads like a paragraph with an inline call-to-action, which I think we can make more clear/distinct.

We need to account for two states:

1. The state when no pages exist (which is currently mocked)
2. The state when a page exists other than the home page (i.e. /) — e.g. if I start by creating a page "Foo", after the generator runs this splash page is still needed. (We have a problem with the existing DX because it throws a "page not found" error once any page is generated, which is super confusing if the page isn't home.)

When the home page / is generated, this splash page will no longer display.

Ideas:

• This section could:
  1. provide info about the current state
  2. list pages with links (for the case where there are other routes that exist BUT home does not exist)
  3. have a distinct call to action to generate a new page (TBD what this does)
• For CTA: Can we be more instructional here via a modal or tooltip (with the option to read Docs)? Sending people off to read the CLI Doc feels, well, potentially intimidating. But saying something like, "from the CLI, type in `yarn redwood generate page my-page" feels easy peasy. And we could also then point them to a next step, like "See all the things you can generate in the CLI Docs" or "Ready to learn more, check out the Redwood Tutorial"
• Layout is really solid, but I wouldn't be opposed to more top/bottom whitespace if it helps the section stand out

B)

A unique icon (along with the title) for each block header could help break up the visual scanning.

I'm so mixed on the "Examples" section because the potential examples (To-Do app and Example Blog) aren't very 🤯 Also, they're both desperately in need of updating. Thoughts/suggestions?

Section Titles:

• Tutorial: the best way to learn Redwood
• Docs and Cookbook
• Join the Community
• Become a Contributor

Screenshot

[alicelovescake]

Thanks for the actionable feedback @thedavidprice . Your explanation around when splash page should display was helpful.
Hopefully my new changes will improve DX!

Here is what I've done in the new commit:

• Section A accounts for 2 states: a.) no pages created b.) pages created but not homepage. (See screenshots below)
• If state a.) occurs, CTA is changed to easy to understand CLI command
• If state b.) occurs, list of created pages with links is displayed. (No CTA b/c they should know how to create a page)
• Whitespace added to give more space to Section A
• Section B has new icons on resource cards
• "Example" resource is switched out for "Join the Community" (link to Discourse Forum)

Notes

Re: Examples resource: Having an example is helpful, we can always put it back if the examples are ever updated. That said, I picked the blog example because it has the most features and documentation. So up to the team what you guys think is more important to have on now!

Re: Copywriting and CTA: I want to balance between having a strong CTA and being succinct. Happy to change or add any info that you think should be on there.

No routes created

Routed created but no homepage

[alicelovescake]

Is there already an Interface for routes? I'm passing in an array of routes here and just using the type any [] because I couldn't find a type for routes

[dac09]

Hey @alicelovescake - there is indeed a routes interface - you can import AvailableRoutes from @redwoodjs/router.

This particular interface gets updated dynamically (using type generation) based on the routes you have in the project.

Not sure if it makes sense to use here, but will leave that to your discretion.

[cannikin]

This looks amazing @alicelovescake thanks so much for doing this! That dark mode... 👀

Redwood was heavily inspired by Rails and their first-run/onboard experience which is, arguably, not perfect, but here's what they do:

• The splash page is only shown when you have zero routes. As soon as you create any route, whether it's the homepage or not, the splash page goes away (that's our current behavior)
• There's a special development-only route, I believe it's http://localhost:3000/rails/routes which lists all the routes in one place (the link and path to the page that's going to be rendered)
• There's also a handy command-line tool rake routes which displays them all in a similar format

Rails routing syntax is much more advanced that ours, you can do all kinds of nesting and redirection so it can be tough to just read through the route file and immediately figure out what's going on. Ours is a much simpler syntax so we may not need that URL/CLI tool to display them all right now.

My vote: I don't think we need that page to show forever until you route a homepage. It's not like create-react-app where you actually get that first setup page as a real component that exists in the project and you can easily remove it. In this case it ends up being a "magic" page that you can't do anything with. I'm thinking of an app where you spend the time building out the backend, before worrying about marketing pages, but you can't seem to get rid of that page.

We've talked about adding a dev "toolbar" that's maybe a little 20px tall strip position: absolute at the very bottom of every page of your site that gives you quick links to things like the GraphQL Playground, Prisma Studio and more (only present in development, of course). It could be neat to add a "Getting Started" link to that bar so that you can get back to those links even once you do route a homepage. Maybe add a "Routes" link as well!

[alicelovescake]

Thanks for providing the broader context and your vote @cannikin! Since your suggestion of removing the splash page when routes exists is different from what @thedavidprice suggested around having separate states, I'll let the team decide and make the change accordingly.

Personally, I agree with you Rob that having a page a developer can't get rid of can be annoying. Yet, the alternative is the 404 page that they can't get rid of, and that can be equally annoying plus confusing like David mentioned. It comes down to which is a better DX experience. I think the splash page is less about showing them their current routes, as much as it is about helping the developer understand why they are looking at the page they are on.

Looking forward to everyone's feedback!

[cannikin]

I'm all for improving the 404 page (in development) that gives a message like:

To get this page to resolve: create a page with yarn rw generate page MyPage / and voila!

Generating a page creates a route as well, and you'll be good to go!

I think if this is the first web application you've ever made, yes it could be confusing that the splash page goes away and now you're getting a 404. But for your second to infinite web app, you'll totally understand what's going on (there's no path/page defined in your Router). I don't think we're optimizing to someone's first ever web framework, though, so I'm okay with that!

[margalit]

Heya @alicelovescake and @thedavidprice. I played around with the styling and messaging, the key changes were:

• Referencing the route as "a page at the / path" instead of "a homepage"
• Listing the paths beside the pages names

My thinking was that explicitly using the term "path" would make more sense since this is the prop that needs to be edited in the router to make this screen go away. I’m also using the code style for each of these to indicate that this list is generated from code.

Dark

Before generation	After generation

Light

Before generation	After generation

Here are the four commits if you’d like to cherry-pick them, they also contain a few subtle styling and layout changes. Let me know if you’d prefer a PR:

• 13ec46c
• bf72af3
• 8f1a755
• c0611fe

[thedavidprice]

Hi @margalit The Page+Path idea is good DX as that's what a dev will see in Routes.js file. Keep it!

My initial questions were more about information architecture, specifically shifting visual attention onto the Page Links once they are generated. The following comments are referring to the screenshot below. I'm open to discussion and pushback about any of the following comments.

Lastly, thank you for taking the time to dig into the details here. This is the initial experience with Redwood for everyone — it's worth the time and effort!

Section 1.a

Once a page (other than /) is generated, this is the most important content on this splashpage and needs visual prioritization. (It might just be that there are a lot of words directly above.)

Section 1.b

This is effectively a title and seems too long. Maybe "List of Pages by path" or something similar?

Section 2

This feels like a callout section. Currently, it's given visual priority being first and having the same type treatment as the next sentence (which is the description/title).

I also suggest adding the instructions to create a home page; yarn redwood generate page home /

---

[margalit]

Hi @thedavidprice, thank you for the feedback. I absolutely agree it is worth spending the time to make this a nice experience seeing as it will be the first introduction to Redwood for many people. I’ll try not to hold this up since we've all agreed it is a better experience.

I wonder if the information architecture is getting lost since I’m currently treating it as "step two" of the splash page rather than a "routes page". I think it would help if we either:

a) Explicitly make this a two step splash screen by adding a checklist for both steps ie:

• Create your first page (yarn rw generate page mypage)
• Create a home page (yarn rw generate home /)

b) Replace the page once we have any pages with a "routes page"

• List of routes in a table with name and pathname
• Remove the welcome message
• Remove the card links

Let me know the preferred approach—they’ll both mean developers won't hit errors after generating their first page. If we go with b) we might be able to make this page publicly available in the future in development (similar to rails routes page).

[thedavidprice]

Completely agree with this aspect being challenging:

I wonder if the information architecture is getting lost since I’m currently treating it as "step two" of the splash page rather than a "routes page".

And this might be a reason why, in the long run, we end up with another solution for what I suggested is the core problem to focus on solving, i.e. "after the dev server is started or a page is generated, the user should not immediately encounter an error page". However, for now I don't think we should re-work this existing implementation with either of your suggestions A) or B) above. (Maybe in a follow-up PR after further discussion in an Issue?)

For now, I'd really like to get this PR merged to be included with v0.37 (publishing later this week). I know I got fancy and introduced IA (😉), but to summarize the crux of my suggestions ==> I just don't want anyone to miss seeing the list of page/route links, which I think can be avoided in this PR via layout and styling.

y/n/maybe?

[thedavidprice]

Status Update

Sam and I have been communicating on Discord to iterate more efficiently. This is in a good place and I'll coordinate to include in the v0.37 release.

We can collaborate on CI errors once final version is in place.

Thanks all!

[alicelovescake]

Status Update

Sam and I have been communicating on Discord to iterate more efficiently. This is in a good place and I'll coordinate to include in the v0.37 release.

We can collaborate on CI errors once final version is in place.

Thanks all!

That's awesome! I'm here to lean in if you guys need any help to the finish line!

[thedavidprice]

Merging this now! Huge WELL DONE to both @alicelovescake and @margalit Appreciate all the work you put into this 🚀