React-styleguidist: UI improvements proposal (UI 2.0)

[sapegin]

We keep adding new function and new “buttons” to the UI and right now it’s inconsistent and far from perfect. Adding more features (and there are plans and wishes to do that) will most likely destroy user experience completely. I was thinking about that for a long time and here are my thoughts.

Goals I want to solve in this issue:

• Improve developer experience (component development process);
• Simplify and streamline the UI;
• Add UI extension points for plugins.

Styleguidist UI consists of these three “levels” (and actions you can do on each level, with some future plans):

• Global (toggle sidebar, toggle props/description, switch background, close isolation = go home);
• Component / section (get anchor link, open in isolation);
• Example (open in isolation, toggle code visibility, show snapshots).

As a possible solution I see something like this:

Sorry for my drawing skills but basically we’ll have toolbars for each “level” that could be possible to extend from plugins plus (also extendable) tab bar for each example (this was already discussed in a relation to the plugin API).

Related issues: #354, #333, #327, #424, #421, #235.

Any feedback? Some design help would be very useful here ;-)

[n1313]

Call me biased but I think that current UI is alright and with exception of #350 I don't see any obvious places that need improvement. Ease of access to information, speed and responsiveness of the application and code parsing features like JSDoc support play a much bigger role on the developer experience than UI bells and whistles, in my opinion. As for extensions and plugins, those are probably cool to have but are not related to UI, apart from the question of "where do we put all this new stuff" which I would say should be asked only after we do have that new stuff.

[sapegin]

These are not bells and whistles, these things are required for the plugin API, not something that we can do after that. There are needed as well for almost any new feature that requires a new UI (some of them are listed in the issue). And we already have issues like #235 that cannot be solved by just moving links around.

Plugin API has a very high priority because the more users we have the more features they want and less likely I’d want to have all these features in the core.

[sapegin]

/cc @okonet @SaraVieira @MicheleBertoli @stepancar @Knorcedger @aaronjensen @skidding

[Knorcedger]

From a usability perspective, having an always visible but unobstructive toolbar is in my opinion superior to links that appear on hover. I like and support the idea.

P.S. The specific icons are not the best :)

[sapegin]

@Knorcedger I hate these links ;-)

Icons are just to show the idea, from Font Awesome. Any better candidates? There’s the whole list of actions in the issue description (some of them are new like toggling props (I really want this) :–)

[MicheleBertoli]

I love the current UI, and I agree icons would make it more scalable.

[SaraVieira]

@sapegin Icons sound like a great idea.

By toggling the props you mean that the user would be able to collapse the props ?

[sapegin]

@SaraVieira Yes, because you don’t need them when you’re developing a component. And for some components they occupy a lot of space.

[sapegin]

@MicheleBertoli I mostly like it too except these ugly isolation mode links ;-)

[SaraVieira]

You mean like this:

I can start with this small fix 👍

I will start working on this tomorrow

[sapegin]

@SaraVieira Yeah, exactly 😬

It will be a small fix as soon as we implement a global toolbar where we could put that switch — do you want to help with that too? 😊

[SaraVieira]

@sapegin Sure, tell me where to start 👍

[sapegin]

I think we can start from simple things like components for toolbar, toolbar button and global toolbar itself (I think it should be fixed in the bottom left corner inside the sidebar if we have a sidebar or just floating).

[SaraVieira]

What will be the links there ?

[sapegin]

These are all I can imagine:

• Global (toggle sidebar, toggle props/description, switch background, close isolation = go home);

So we can start from home and then add props toggle.

[SaraVieira]

Sure, I'll start by adding the buttons to go home and create a nifty
animation for the sidebar and I can also pick up the individual dropdown of
the props and then we can talk about the better way to do the all props
dropdown.

Should we put the new logo on the header?

On Fri, 5 May 2017, 09:58 Artem Sapegin, [e-mail] wrote:

These are all I can imagine:

• Global (toggle sidebar, toggle props/description, switch background,
  close isolation = go home);

So we can start from home and then add props toggle.

—
You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub
https://github.com/styleguidist/react-styleguidist/issues/426#issuecomment-299415661,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABALdY0RH0kpSu3-WX-zYe07ZR6lFfbaks5r2uTNgaJpZM4NPU0w
.

[sapegin]

What do you mean by “dropdown of the props”? ;-)

I’m not sure about the logo because the text can be changed but would be nice to have it somewhere.

[sapegin]

[sapegin]

@cef62 @SaraVieira The new toolbar is in the ui branch ;-) I’m going to work example toolbar + tabs and then on the plugins API proof of concept.

[sapegin]

One more sneak peek:

I’m also thinking about using the same tabs UI for showing props/methods, hidden by default (possible to change by config option) and possible to extend by plugins.

[okonet]

I think the "link" icon should be connected with the heading. I really like how GitHub shows them. Do you think we still could show them together?

[sapegin]

@okonet We can make header a simple link but I don’t want to show anything on the left side, it didn’t really work for Styleguidist (can be hidden on small screens, having something on both sides of the header was strange).

[sapegin]

I’m going to release these changes next with (with slight modification):

Do you have any feedback? You can try it in the ui branch.

[sapegin]

Thing I know I’m going to change:

1. Add links to component headers.
2. Probably remove the link button from component toolbar.
3. Think more about buttons outlines (appreciate any ideas here).
4. Maybe change title of Props & Methods tab if I could find a better one.
5. Try to move example tab (Code) and toolbar outside the example border.

[iamstarkov]

@sapegin how does it look on small screens? we used to hide sidebar and props for small screens

[iamstarkov]

and make preview container as wide as possible

[sapegin]

No changes for small screens so far bug I should test it again ;-)

and make preview container as wide as possible

What do you mean? Remove max-width?

[iamstarkov]

i checked it now, nvm preview component seems good

[sapegin]

The first part is done in 5.4.0! 🦆

[iamstarkov]

@sapegin its very nice

[apennell]

I think it would be great to add a carat icon or something like that on the Props & Methods link, and possible also the Code button, to indicate more clearly that clicking it will expand more information. I like keeping them hidden (as noted earlier, this list can get long), but it's very important information and I think the link may be too easy to overlook as it appears right now. Adding something like an icon would at least indicate that the link will do something more without having to hover to notice that it's link.

[sapegin]

@okonet @SaraVieira What do you think? (See the previous comment ;-)

[stale[bot]]

😴 This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week without any further activity. Thank you for your contributions.