Simple WelcomeScreen

[qooplmao]

What's up?

I am planning on using react-cosmos to demo components to non-technical members of my company and the current welcome screen that is displayed has things which they will only find confusing ("mock Redux state", "fixtures", etc).

Ideally there would be a "basic info" version of the WelcomeScreen that just had the bare minimum information required for a user to see what they need to do ("Components are listed on the left side. If you are looking for a particular component you can use the search box at the top left.").

Mkay, tell me more...

One way I can think of doing it would be to have a boolean argument in the cosmos.config.js file (showBasicWelcomeScreen: boolean) and then passing that down to the WelcomeScreen component (by way of PlaygroundOpts and the component-playground).

It may not be ideal though (parameters all over the shop being passed through everything), so understandable if you didn't to go that way.

All that being said.. I may be missing something stupidly obvious that would allow me to do the above myself. Any thoughts/pointers?

[mpeyper]

+1 for this. Now that I have a few fixtures up and running with proxies (including redux), it feels odd to see a message suggesting I should set up a redux proxy. It's not a huge issue, but it's the first question I get when I try to show it off to others on my team.

Perhaps I will take a crack at this if I can find the time (not likely to be soon so if anyone else wants to have a go, please don't hesitate).

I have a few ideas for how to go about this:

• A toggle in the config as @qooplmao suggested
• Flagging a fixture as a default view as displaying it instead of the welcome screen
• Providing a custom component (likely as a configurable path with sensible default) to render as the welcome screen

Any thoughts or ideas are welcome.

[ovidiuch]

Hey @qooplmao @mpeyper,

Thanks for pointing this out. Here are my thoughts:

• We can definitely improve the current messaging, but I don't think we'd find a one size fits all so it sounds like the best solution is to allow complete customization of the intro page.
• I'm not a big fan of the "customize everything" product philosophy, but I think this would be in line with another initiative I've been thinking about lately: Making the Playground screens markdown-powered. By doing this, I'd later want to somehow import the Github release notes and offer a change log inside the product. I think this would be a nice way to keep users up to date and suggest informed upgrades.
• So if the Playground screens become markdown, this would be just another markdown page. Maybe we can add an introPage option pointing to a .md path, defaulting to cosmos.intro.md.

Wdyt?

[mpeyper]

I think markdown is a great idea.

[qooplmao]

Yeah, I think the markdown idea is a winner.

To be honest, originally I was going for a customizable WelcomeScreen but the single boolean seemed to be the simplest to implement so I went that way. It doesn't really seem fair to me to bring up an idea without working out a possible route, but the Markdown approach wasn't even in my periphery.

[ovidiuch]

Does anyone have experience with markdown libs and is able to recommend any, possibly with good React compatibility?

[mpeyper]

I haven't used any of them myself, but I've been looking into some for this.

• react-markdown - Most popular and provides heaps of options
• react-remarkable - A wrapper around Remarkable, a popular and highly flexible markdown renderer. Also, it's made by @acdlite so it's got a good pedigree
• react-markdown-renderer - Another wrapper around Remarkable

[mpeyper]

Just an update on this.

I've been able to replicate the existing welcome screen but instead of being fixed output in the component it is loading it in from an external markdown file.

Issues:

1. The markdown file is not being watched to trigger an page refresh when it change
   • Manually refreshing the page shows the change
   • I'm not sure what that means for exporting the page
2. Remarkable does not appear to have the ability to add classnames to the rendered elements, so the styling needs to be applied element type instead
   • My less is a bit rusty, but I think that can overcome by applying a class to the container and nesting the styles under that?

Questions:

1. How much styling should we provide to the rendered elements?
2. Is the only screen we want to allow an override for the WelcomeScreen when "You're all set!", or are there other screens to consider?

[qooplmao]

There is a react-remarkable PR for adding plugin support (or you could temporarily duplicate the class from the PR), which would mean you could use remarkable-classy for class names.

The only really screen I'm specifically bothered about being able to change is the WelcomeScreen as that's the only part that user are really forced to see/deal with. Every other page requires a conscious choice on the users behalf to visit so I see it more as something they should deal with (that being said, the WelcomeScreen could be used to add an explanation for whatever sticking points an individual user base has). I do concede that I am thinking very selfishly in this respect, though.

[mpeyper]

remarkable-classy allows the markdown to specify the classes it wants, but not for us to apply a class to all elements of a type, e.g.

# This is my title

this is my text

will always generate

<h1>This is my title</h1>
<p>this is my text</p>

There does not appear to be a way to have it output

<h1 class="header">This is my title</h1>
<p>this is my text</p>

without changing the markdown itself.

As I said though, I think this can be quite easily overcome by wrapping the markdown elements in a div and using that to scope the style. I have to admit that less (and css in general) is not my strong suit, so whatever I do will likely be either wrong, or can be improved.

[ovidiuch]

Is the only screen we want to allow an override for the WelcomeScreen when "You're all set!", or are there other screens to consider?

This taps into a bigger question. Right now there are three onboarding screens. The first two are shown when configuration is incomplete and the last one sticks forever. Short term we can override the final onboarding page with the custom introPage. Long term we could add a persistence dimension to onboarding screens, meaning we should be able to click "Got it" and not see it again. Then we could stack onboarding screens, release new ones periodically, etc. and have the intro screen show when all onboarding screens are dismissed.

How much styling should we provide to the rendered elements?

Just like with Markdown in general, styling should be standard. A single style for headers, paragraphs, links, bold, italics, code and that's about it.

[qooplmao]

Long term we could add a persistence dimension to onboarding screens, meaning we should be able to click "Got it" and not see it again

Where do you imagine the persistent state would be stored? If it's in the local storage then users would run into the same issue as my current one, in that they would have to deal with a bunch of a screens that they had no idea about.

What about just have the custom WelcomeScreen on cosmos-export? The onboarding screens are only useful to those that are developing components, whereas by the time it's been exported it's kind of past the point of onboarding.

[ovidiuch]

Where do you imagine the persistent state would be stored? If it's in the local storage then users would run into the same issue as my current one, in that they would have to deal with a bunch of a screens that they had no idea about.

OK so maybe the problem is the current welcome screen is bad for everyone. Nevermind my idea of a more advanced onboarding flow. It's too abstract and doesn't help reach a solution here. Going back to what we have now. These are the existing screens:

1. Loader index.html is missing (configuration error)
2. No fixtures
3. "You're all set! But did you know..."

It seems like 1) is more troubleshooting than onboarding. So really the onboarding is split in two screens: Before and after you have fixtures. Before "no fixtures" screen is probably fine as you'll only see it once and it provides useful instructions. But the "You're all set!" screen you see forever. I don't think it ages well nor does it apply to a wide array of people. How about we try to improve it for everyone before we try to make it customizable. We might find a common version that suits us all (at least for now).

I personally learned to ignore it because I see it daily, but out the top of my head I can object to the following:

You're all set! But did you know...

"I'm all set!" one year later, really?! :P

You can mock Redux state and build custom middleware using proxies?

This shows up even if I have proxies.

You can search for components and fixtures? Try it, it's all warm and fuzzy.

Useful info, but it doesn't point to the left nav nor to the s shortcut.

You can load CSS, polyfills and other files globally?

Also doesn't check if I do this already. I do.

Be a part of React Cosmos by becoming a contributor.

Maybe this is too much for everyone to see on their dashboard?

---

I guest we could compact the info on proxies, global imports and contributing into a link to the entire Cosmos documentation.

So, what would your ideal welcome page look like?

[qooplmao]

To be honest I'm looking at things from 2 different environments.

For developers (when running as a live system) there could be hints/tips/information that could be used for onboarding and notifying them about any updates. This could be, as you said, controlled using persistence so that devs could turn hints/tips off and on or skip through them.

For user/browsers (after it has been exported), I would assume people would use this as a demo, so the simple "Components are on the left. Search box on the top. For more info about using this system see [docs url]".

I see a lot of benefit in the WelcomeScreen reminding devs of what is available in the system, especially when there are updates that may not be immediately obvious, but once the system has been exported those messages become less beneficial.

[ovidiuch]

@qooplmao I agree with your vision. I propose this order of steps:

1. Focus on the user-centric screen first (instructions on how to use the Playground).
2. Find a set of instructions that appeal to the general public.
3. If this screen is not satisfactory for anybody involved in this convo we'll continue to consider the option to customize this screen.
4. At first this will replace the WelcomeScreen for both dev and export modes (I don't think we'll miss anything from the existing screen).
5. Separate thread: Replace the WelcomeScreen in the dev mode with a more elaborate system of dismissible hints and updates.

Wdyt?

[mpeyper]

Personally, my ideal welcome screen would be no welcome screen at all. By this, I mean what I want to do from the index is make is as simple as possible to select a fixture to view.

I propose that perhaps, if no errors are found and fixtures are present, the side bar should be given the full page width, with a larger search box and a more real estate devoted to displaying the list of fixtures.

Thoughts?

[ovidiuch]

@mpeyper interesting idea. I can see some variation of that work. FYI, I just published a draft of the entire Cosmos Roadmap in react-cosmos/react-cosmos#546, which has an item related to this topic:

Separate install onboarding from usage onboarding (the former should only be shown in dev but not in static export)

I'd like to continue the conversation in this context. I believe it's a good strategy to separate the onboarding flow meant for installing and configuring, versus the onboarding flow for using it. I also agree that the Cosmos export should have a basic onboarding for anybody to follow, also that the Playground should not show a useless messages for the 1000th time and focus on popular use cases instead (eg. quickly selecting fixture).

But my question is: Where does the separation between dev server and static export happen? Install onboarding has nothing to do in static export, but other than that is there any point in having separate communication? If it's about dismissable messages, the static export should be able to store to localStorage as well, at least if it's powered by a webserver.

[mpeyper]

@skidding, sorry it's taken so long to respond, I only just noticed this.

I don't actually use the static export feature and use cosmos as a purely dev time tool. I have deployed exported storybooks for testers and non-devs to use, but that is usually for component library style projects (storybook is easier to to create lots of variations of a single component).

For me, the installation onboarding flow was close to perfect. The hints cosmos gave to where the issues were and what steps I needed to take to get my first fixture up and running was super useful. I wouldn't change that at all.

Once I had my first feature, my focus shifted to the component I was developing and I very rarely returned to the welcome screen so any messages it would be showing at that time might as well not exist. If I encountered any issues at dev time the react error overlay does a great job of helping there (particularly with React 16's improved errors). When the component is done, it's integrated in the app and I move on the next one and repeat.

I have yet to find someone who struggles to navigate the side menu and/or filter the list for what they are looking for, either devs and non-devs, so I'm not sure what is needed in the onboarding flow for using it other than making the list more prominent. In this respect, my post-installation requirements for the welcome screen are much the same. I usually only hit it because I've begun development on a new or existing component and just need to quickly find the fixture for it.

Does that help with any of your questions?