feat(clayui.com): Add documentation for examples in form of list of links to their stories

[kresimir-coko]

Hey @matuzalemsteles @jbalsas here's a draft for the Examples page.

Here's what I've done:

• I included a couple screenshots I took manually, and the rest are placeholder images.
• I added some copy that we can expand on/alter or whatever, describing Storybook and how we use it
• The examples I added are just the Demos we have, not all components, as I don't think we want all components as that would duplicate all the examples we have in component-specific docs

My thoughts going forward

• We might need some illustrations instead of screenshots to showcase the examples, as they are visually quite complex for the low resolution, at least the ones I decided to showcase
• If we do want to have a component frontpage like in Carbon Design we can utilize the Component homepage for that I made recently

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit d67a6ab:

Sandbox	Source
serverless-pond-89bii	Configuration
red-snow-r6tm1	Configuration

[matuzalemsteles]

We might need some illustrations instead of screenshots to showcase the examples, as they are visually quite complex for the low resolution, at least the ones I decided to showcase

Yeah, I think screenshots are probably not a good option, maybe small illustrations of simpler lines, nothing too complex.

If we do want to have a component frontpage like in Carbon Design we can utilize the Component homepage for that I made recently

Yes I also think it would be a good option, to explore the components. Not everyone knows the components by name, it would be good both to fill space and to facilitate the search for the components.

[kresimir-coko]

@matuzalemsteles I agree with both of your points, do we need illustrations for components too, in that case? Some can get pretty complex very quickly, like Dual List Box for example

[matuzalemsteles]

@matuzalemsteles I agree with both of your points, do we need illustrations for components too, in that case? Some can get pretty complex very quickly, like Dual List Box for example

@kresimir-coko yeah, the good thing about the illustrations that don't need to stick to the details of the components, but I'm not sure if that would be a problem. So for more complex components, in the illustrations it will not be necessary to be so faithful, because it will decrease the maintenance cost if the component changes some detail.

I think we can go now with the examples and then ask for help from the Design team to create for the components illustrations, due to the current quantity of components. We can also try to do it ourselves.

[bryceosterhaus]

Looks pretty good, I am unsure about screenshots for our full page examples though. We could even just list them out as links and I think that would be helpful.

[kresimir-coko]

Hey @bryceosterhaus, I've made changes to this since monday.

• I ditched the screenshot approach, then
• I tried the iframe approach but @jbalsas steered me in a better direction, so
• I just made them into links that point to their stories.
• I also made the change to the text that you suggested.

What should be our next step regarding this, should we keep it like this until we get illustrations?

[bryceosterhaus]

Just had a comment about using the List component but other than that, looks good.

[bryceosterhaus]

Item needs to be the first descendant of ClayList, otherwise it won't be semantic.

Also, I think it'd be better to not use List and instead just ClayLink with line breaks between each item. I think the list looks a little odd for this case.

[wincent]

Makes me wonder whether there should be a check (only when process.env.NODE_ENV === 'development') that looks at the children and makes sure there are no non-list children... (or at least no children that are definitely the wrong type of Clay component).

[kresimir-coko]

This attempt of mine might have demonstrated a need for a new prop (maybe a boolean link) for ListItem. I wanted to make the whole List Item a link, not just the text inside.

What're your thoughts on this prop @bryceosterhaus @matuzalemsteles ?

[matuzalemsteles]

@kresimir-coko I think we would still have problems with semantics. To reverse this problem we would need to modify ClayList and ListItem to not use ul and li for cases with Link or Button, I don't know if this would be very friendly.

[kresimir-coko]

@matuzalemsteles not sure it's not bypassable tho, I think that with some CSS we can make the a full width and height and thus making the entire area of the li clickable.

[matuzalemsteles]

@kresimir-coko I'm not sure what you want to say, would it be changing the CSS to support this? I was referring that we could replace the tag ul and li with a div and a or button using the same classes, this is the most recommended for these cases, I suppose Clay already supports this since it extends from the bootstrap.

[kresimir-coko]

@matuzalemsteles Yes, I'm suggesting that we keep the ul > li > a hierarchy, and just manipulate the css so that we can have the a element cover 100% of the li's size

[matuzalemsteles]

Oh, now I get it 😁, Hmm 🤔. @pat270 what do you think?

[kresimir-coko]

@bryceosterhaus I've removed the ClayList and made the ClayLinks display: block so they render as a vertical list. That's pretty much it! :) LMK if anything else comes up.

[bryceosterhaus]

Looks good!