Improve the general beginner experience

[kptdobe]

Code of conduct

• [X] I agree to follow this project's code of conduct.

Description of issue

Thanks for the library, it saves a lot of time to build "Spectrum" UI (without the need of React). I have quickly built a first UI but I have lost a lot of time with basic simple things. I do not want to create an issue for each of the little thing I have found but I hope that my honest and constructive feedbacks will be considered to improve the beginner experience. Here is a non-exhaustive list of what I encountered (if desired, I can extend it with the other things I find). A lot of it is related to the documentation.

• [ ] Getting started
  • [ ] if you copy/paste the first block of code (and uncomment the script...), you do not get the expected result: you must add some background colour, width and height to get the dark background. This is confusing, I would expect that the sp-theme would do that for me or the doc to show everything needed. This was the first point of contact with the library and I was already frustrated.
  • [x] the Read about the full range of style customisation provided by @spectrum-web-components/theme. link is broken... it would be a useful reading because the mix between the component styles, the theme and the layout requires some experience.
• [ ] General documentation navigation: if you click on a component, page opens but navigation context is lost, you are always at the top. This is so annoying, it drives me nuts, especially with the ones at the bottom. I feel like I keep scrolling. Not sure why nobody complained about that before.
• [ ] For each component, the doc starts with the usage (includes). Great. But if the example(s) require other components, you need to find the includes yourself and a copy/paste is not enough to have the sample working (that's when I need to scroll to find those required components and I keep scrolling...).
• [ ] Playground - The playground could be a great idea if it would be usable. Many example do not work for me (Chrome latest). [One simple example[(https://opensource.adobe.com/spectrum-web-components/storybook/index.html?path=/docs/dialog--alert-information), 2 bugs:
  • [x] nothing happens when clicking on the buttons
  • [x] the code shows [object...]
  • [x] Also, I keep chasing the "show code" button which is not available in the Canvas view.

Components specific:

• [x] sp-theme
  • [x] self explanatory:
• [x] sp-color-wheel and sp-color-loupe
  • [x] Is someone using those ? Why user cannot select black and white which is certainly a valid choice no ?
• [ ] sp-toast
  • [ ] alert vs toast: this is somehow described here https://github.com/adobe/spectrum-web-components/issues/82. It is closed but you can still find spAlert in the code. Which I expected to use (nice, visual, easy...) before realising it is doc specific. Making it a component or at least explain how to build it in the playground would be a great
  • [x] timeout: the property is not documented and even worst has some logic you cannot imagine. I have lost almost an hour before finding this: https://github.com/adobe/spectrum-web-components/issues/351

Nothing complex to fix but as you can see my beginner experience is not so great. I am even considering using another library for my UIs. Happy to provide more constructive feedback if needed.

[Westbrook]

@kptdobe Thanks for the expansive feedback! 🙏🏼

We're getting started today with #2292. 😬

Beyond that, we're always excited to receive PRs, so feel free to get into some of the questions and suggestions you have here on your own. Happy to support here, in PR, or internal to Adobe as you get introduced to the project.

Some initial thoughts on the above:

if you copy/paste the first block of code (and uncomment the script...), you do not get the expected result: you must add some background colour, width and height to get the dark background. This is confusing, I would expect that the sp-theme would do that for me or the doc to show everything needed. This was the first point of contact with the library and I was already frustrated.

1. We try really hard not to suggest that we control anything but the elements that we ship in our packages, this includes NOT styling text, etc. by default. I agree that we should be more assertive with that being something we DON'T do, so that there are less blockers in early adoption.

For each component, the doc starts with the usage (includes). Great. But if the example(s) require other components, you need to find the includes yourself and a copy/paste is not enough to have the sample working (that's when I need to scroll to find those required components and I keep scrolling...).

2. As far as "require other components", it would be great to get some more precise information around where you're seeing this issue. Sometimes we are documenting specific things and other times we document collective usage and better understanding where one or the other isn't serving users would be super helpful!

Many example do not work for me (Chrome latest).

3. A number of our demos are not "functional" in that they're not bound to an application, and we don't want to make any assumption on what that application might look like. This may be a place where we could be more communicative about that fact, and any specifics you could bring to this point would help shape what that might look like.

the code shows [object...]

4. This is a weird upstream bug of the tool we're using. I can say that it you toggle it off and on a second time it should start working again 🤦🏼‍♂️

self explanatory:

5. I'm not sure that this is "self explanatory" would you be able to expand on what you're seeing here?

sp-color-wheel and sp-color-loupe

6. Color Wheel is currently a "hue picker" so black and white shouldn't be much of a concern there. Did you look at sp-color-area, these pair together nicely along the lines of https://opensource.adobe.com/spectrum-web-components/storybook/index.html?path=/story/color-area--joint. sp-color-loupe is a subcomponent of the other color elements. I think you may have meant sp-color-slider which follows the same rules as Color Wheel.

sp-toast

7. spAlert is interesting because it is very application bound, and while the library could "vend it as is" it would likely not serve many users and would be API surface we couldn't remove later. I'd love a more vibrant conversation around an API here, and would love to see you start a stand alone Discussion on this topic that we could bring the broader community inside and outside of Adobe together on in order to find the right capabilities to ship there.

Note that I've numbered the conversations above so we can more easily reference them in the future. 😅 Looking forward to your thoughts, and any PRs/Discussion you're able to get started. 🙇🏼

[kptdobe]

We're getting started today with https://github.com/adobe/spectrum-web-components/pull/2292. 😬

Nice, thanks a lot.

2. "require other components"

Half of the components have a dependency. Example: https://opensource.adobe.com/spectrum-web-components/components/quick-actions/ To get the example working, you also need to include: sp-action-button, sp-icon-info, sp-icon-magnify and sp-icon-star. Finding the icon deps is not necessarily straight forward. I understand you document quick-actions but the examples could have a new button "Copy to clipboard everything I need to be able to run this sample" (granularly of course because I do not want to have everything loaded on my page.

5. sp-theme: "self explanatory

If you check the image, you see the API tab of the sp-theme doc page. property col says undefined and type, default... cols are empty.

7. spAlert

I opened discussion here: https://github.com/adobe/spectrum-web-components/discussions/2299

[najikahalsema]

tracking via #1199

[Westbrook]

Everything has been addressed or ported to other issues. We appreciate your continued feedback and support in those issues coming to a productive close.