[docs]: Create a design system for marble diagrams - a standard for marble diagrams

[BioPhoton]

(UPDATE): I started to collect all outcome and questions here:

Rx-Marble-Design-System

• [ X ] documentation doesn't exist
• [ X ] documentation needs clarification

Description Of The Issue

Why is this important?

Marble diagrams where ever since a very practical and easy way to explain the behavior of streams in a visual way. There are a lot of diagrams out there, but they are not fully explaining the complex behavior or more important internal workflows. Also, there are different scenarios for some operators that are only possible to explain in diagrams if we would have internal workflows visible. Furthermore, there is a lack of a standard for these diagrams.

What I want to create is: A public open source standard of drawing marble diagrams An easy and more important quick way for everyone to create marble diagrams If the standard is done I will create diagrams for all operators and their different scenarios

Here is where I started with: https://docs.google.com/presentation/d/1LlVmTEcoc1LRV00Tp-rDp4kopI-NobC9S2w-w5pC_JA/edit?usp=sharing

As you can see there are a lot of questions to answer. What I would need is people that help me to discuss several edge cases to generate this standard. Also if the standard is finished I would need a second pair of eyes that help me to double check the drawings for all the operators.

[kwonoj]

This is quite interesting but I am bit unsure if we can define something. We define semantics of marbles, but does not define how does it visualized: i.e even in ascii marble we allow all chars as marble tokens vice versa. Also even if we have something not sure if we can enforce to everyone use those instead of each user's page design.

[niklas-wortmann]

Hey there, I really love that idea, especially for the docs web page. Ideally it comes with consistency and clarity.

@kwonoj Maybe I get you toally wrong, and for sure we can't enforce anyone to use this kind of semantic, but is your point really just about semantic? I think we can define some kind of standard. I think we already did in some way (see http://reactivex.io/rxjs/manual/overview.html#marble-diagrams)

Anyway I definetly think, that this is a topic we should discuss at the next core team meeting!

[kwonoj]

@JWO719 I don't think what we represented in http://reactivex.io/rxjs/manual/overview.html#marble-diagrams is same as proposal here. i.e font, lines, color, shaping and vice versa design aspects are something we don't define - in our diagram what we defines is just semantics. i.e we use x as error in attached pics, but in ascii marble we do use # instead, etcs. We don't enforce what kind of visual representation as long as it's described to follow our semantics.

[niklas-wortmann]

For sure we can't enforce this level of consistency across all users of rxjs. Maybe I'm a bit newbie to oss for those kind of stuff. But in my point of view, this is a thing we (core team) should agree on and spread it. So that maybe at some point the community will stick to it. I just think that most of the marble diagramms hide the complexicity of operators. Maybe that's good for some use cases (operator- or target group wise) but in general we should make things as clear as possible.

[kwonoj]

But in my point of view, this is a thing we (core team) should agree on and spread it.

If this is only for semantics, I would agree and it's widely accepted already. I would disagree for whole scope of proposal as something we'd encourage, like design elements. I don't feel we'll introduce some guidelines like fonts, element design and vice versa. In short, I believe given proposal's scope is too broad for core.

For semantics, we do already have it https://github.com/ReactiveX/rxjs/blob/master/doc/marble-testing.md#marble-syntax (and some extended proposal here https://github.com/kwonoj/rx-sandbox#observable-marble-diagram-token-description).

[BioPhoton]

@kwonoj About your schemantics: You can also create a design manual for ascii marbles: https://docs.google.com/presentation/d/1UqVkGH_mZ10WvbPqEAUE0nsJUkbvfvGXfFEWghbA4RA/edit?usp=sharing

The "standard" should help to draw and understand these diagrams. ascii marbles dont give much options to show internal workflows ect.

Here are some operators I tested to draw:

[BioPhoton]

I don't feel we'll introduce some guidelines like fonts, element design and vice versa. In short, I believe given proposal's scope is too broad for core.

Don't stick too much with font, and exact sices. The idea of a design system is way more than the design aspect. It's a set of standard elements (like your ascii marbles) that can be used to create a diagram in a way you don't have to think about spacing, what to use for unsubscribe or if your colors are also good for colorblind ppl.

if you explain marbles in tge docs (which is the case) you should think it through, consider edge cases, test it against complex problems and sume up everything at obe place for ppl to read. This is the idea of the design system. 😀

[srounce]

Good work starting this initiative 👍 Some feedback from a quick glance through the first link:

• This is not a hexagon.

  

• Possible bike-shedding/out of scope with regard to typefaces. Perhaps simply specifying, that description typefaces are monospace, and providing an em-height scale relative to the block size would be more helpful.

• Nested/Higher-order observables aren't going to scale for complex examples (where a formal means of visual description would be most useful).

• A set of rules around hand-written notation would arguably be more useful, also they would also be a better guide to the high-fidelity versions you're currently working on.

• Having special border styles for an observeOn/subscribeOn stage dependant on the scheduler won't work.

  • Are we to have an 'everything else' style for custom schedulers? In which case this doesn't projects that have several custom scheduler implementations.
  • How does this combine with operators like delay for instance?

[BioPhoton]

@srounce Thanks a lot for your feedback!!

This is not a hexagon.

FIXED

Possible bike-shedding/out of scope with regard to typefaces. Perhaps simply specifying, that description typefaces are monospace, and providing an em-height scale relative to the block size would be more helpful. I created some notes for the fonts to elaborate that the actual font family is irrelevant but mono-space and so on..

Could you help me to create the right content for the "font related" slide?

A set of rules around hand-written notation would arguably be more useful, also they would also be a better guide to the high-fidelity versions you're currently working on.

Most of the diagrams will consist of only basic blocks and complexity. The examples are just here to show how details it could go and where the end is. ;-)

Having special border styles for an observeOn/subscribeOn stage dependant on the scheduler won't work.

Removed this option! Thanks

How does this combine with operators like delay for instance?

ATM I don't know. If context would be the border I would do something like this for delay:

But the scheduler is also a "nice to have level detail" and nothing i would draw in every diagram.

I also added some questions to the end of the slide deck. Maybe you can have a look.

[pertrai1]

I think that this is a great idea and if flushed out more, it could be of huge help in getting people more into using RxJS.

[LayZeeDK]

I would suggest not using green, yelllow, and red as default value colors. Personally, I can't unsee "success", "warning", and "error" since it is such a well-known palette.

Additionally, red-green color blindness is a common condition.

[BioPhoton]

@LayZeeDK Thanks for your feedback! Could you help in providing some tools to check the colors?

It would be also amazing if you could take a quick look at slide 5,6,7 and 33 here

And share your thoughts on it.

[srounce]

@BioPhoton https://colororacle.org is pretty basic but it's free and works well.

[LayZeeDK]

Could you help in providing some tools to check the colors?

I have previously used Chrome extensions. If I remember correctly, Spectrum is a good one.

We can also measure the contrast between the colors with WebAIM Color Contrast Checker. This tool can also be used to check whether black or white has sufficient contrast to be used as a text color on a specific value color.

(On a side note, I have actually got a SCSS mixin somewhere that calculates whether a light or dark foreground color should be used on a background color to provide enough contrast).

To be honest, I am not sure that using different colors provide enough value compared to the visual noise that they create. Different shapes are enough and there are a lot to choose from.

If you are absolutely certain that we need value colors, Adobe Color CC has inspiration for other palettes.

[BioPhoton]

Thank you so much for thoughts @LayZeeDK !

I also found this amazing chrome plugin with even more options: chromelens. Also the Adobe Color CC link is amazing because you can search for color blind safe colors. Thanks a lot again!!! :-)

Atm I'm implement the feedback that I got about fonts and sizes. I'll insert some notes in the document about your thoughts on colors and shapes.

To be honest, I am not sure that using different colors provide enough value compared to the visual noise that they create. Different shapes are enough and there are a lot to choose from.

If you are absolutely certain that we need value colors, ...

Im not certain of anything. At the moment it is an adventure for me. I'm trying to find out what the different informations in marble diagrams are and how I can create a design system to make it easy for everyone to create them. Further more I try to answer several questions like what purpose serve different shapes or colors, or how to present subscribe, connect, unsubscribe in an intuitive way.

If you like we can work on some examples that colors are less relevant or show some rare use cases where they are needed. Later we can ask ppl what they think and how they see it.

Here are some ways to use colors that I have created to reason about. Do you have any other ideas for examples? It's also on the design system doc on slide number 34.

[BioPhoton]

@srounce I included all your feedback regarding font sizes in em in the doc under fonts and and later in description .

My em is related to 1 block. I also limited font size and style for specific use. At the moment I have the question if I should have only one font-size for values. Maybe you can have a look and give a last feedback on this question here again the link to my section with the question

[srounce]

Thanks dude, will have a look, I plan on taking some time this weekend to add more detailed thoughts on this.

[BioPhoton]

@LayZeeDK

(On a side note, I have actually got a SCSS mixin somewhere that calculates whether a light or dark foreground color should be used on a background color to provide enough contrast).

Could you please provide it in some way?

[LayZeeDK]

@LayZeeDK

(On a side note, I have actually got a SCSS mixin somewhere that calculates whether a light or dark foreground color should be used on a background color to provide enough contrast).

Could you please provide it in some way?

YIQ Color Contrast (sass-yiq)

[BioPhoton]

The design tokens and components are almost done. :-) One last problem with visualizing the operator context is missing.

Thx again to all the feedback and I hope for some more! Here you can check out the current status: Marble Design System

@srounce Also the font related problems are solved. You may want to have a look. :-)

[benlesh]

There's a lot of great discussion here. However, I'm not sure the team has the bandwidth to support this sort of effort (as evidenced by the lack of traction here). I'm going to close this one for now, just to clean things up. But thanks again for the awesome input and thoughts, @BioPhoton. This is definitely something I'd love to see in userland to see how well it works out.