[Design] Component demo — ready

[aagonzales]

As a user I want to be able to view the live demo component in the 4 different themes as well as be able to see the different variants and modifiers in one window instead of multiple.

[aagonzales]

Feature priorities:

• 1 Theme
• 2 State
• 3 Size
• 4 Variant
• 5 Sub-variant
• 6 Modifiers
• 7 Editable content

Concepts:

Option 1: content switcher

Option 2: tabs & variants in list

Option 3: All in right panel

Option 4: theme and variant tabs at top

High contrast panel

Left panel

Basic fields

[aagonzales]

Here is the direction we're trending.

• Themes use a content switcher like on the color/usage page
• Theme switching is controlled at a global website level. If one component is switched to the Gray 100 theme then all component examples automatically switch to that theme as well.
• Try to avoid dropdowns and show the options are much as possible.
• React code is hidden but can be shown and copied. Ideally the code block content changes with what configurations are applied.
• Link to other dev environments no longer a part of the main demo window.
• Exactly which components we use to display content in the right panel of the demo window is still TBD.

Code panel expanded

View in full page concept WIP

[aagonzales]

Possible components

[vpicone]

Seeing the code update in real time is pretty essential towards making this usable. One of the big issues with storybook is how our code snippets aren't usable.

I don't think having a copy button makes sense without also having the live code that you're copying displayed. I think polaris's live update example for this is a solid example. Something like the basic fields example above is what I imagined (maybe without those framework links).

The show more is tough here since it'd also pull down the sidebar with all the knobs, I think it might be better just to make that area scrollable. One thing to keep in mind is that since the components are in isolation, there's going to be way lose code than as-is, so we might be able to ditch the show more.

[aagonzales]

OK in order to make some decisions around the code block I need a little more insights into what users would want to do with it. Keep in mind this demo window is also for dev and design to showcase what's possible with the component. eventually code, usage and style will all liver harmoniously on one long page together.

Dev needs I'm currently understanding:

• Code update in real time with modifiers
• Users can edit code in code block
• Copy button nested with code, not alone.

Questions (for dev):

• Do we need to show props (like on Polaris?) What are they?
• Would it be ok to completely hide the code by default or would you want to see it up.
• Where is the primary place we want users looking at component code?
• Will/should this component demo replace the React sandbox?
• Window will only ever show react code?
• Is the react code useful to see if you're not a react user?

See https://github.com/carbon-design-system/carbon-website/issues/357#issuecomment-535098372 for context.

[aagonzales]

Code block options - WIP

[jnm2377]

@aagonzales These are my thoughts on your questions:

Do we need to show props (like on Polaris?) What are they?

Yes. This is something that needs work in our storybook, as well. We've heard time and time again from users that they don't know where to find the props. We don't really do a good job of surfacing them, and they are very essential for React, not just for different variations but also for a11y and state related props.

Would it be ok to completely hide the code by default or would you want to see it up.

I'd want to see it up by default but having an option to hide it would be ok.

Where is the primary place we want users looking at component code?

I think existing React users primarily look for code in Storybook, which tbh needs a lot of work because we can do better in a lot of ways. Since we're now React-first, though, I think moving our website to be React and aiming for this to be the main place for users to find code would be ideal because we can better customize this experience than what Storybook currently offers.

Will/should this component demo replace the React sandbox?

No. We still need sandboxes for users to reproduce bugs and stuff.

Window will only ever show react code?

Yes. We're moving towards deprecating vanilla, and the core team will only maintain React. So my take is yes.

Is the react code useful to see if you're not a react user?

No, it's not. But the vanilla code is not useful if you're not a vanilla user. And we're React-first now, so I think if there's any code that we should be showing it should be this.

[mjabbink]

@aagonzales in the case above under Documentation I think the icons would work better on the left. or as in the right side in a column just as a visual cue that you’re leaving the site (not clickable but maybe also clickable?) Could not hurt in this case.

or

no icon and a link on the right side (column) that says something like Go to location or visit location. Maybe cleaner and avoid icons.

[joshblack]

Do we need to show props (like on Polaris?) What are they?

I think it can be helpful, being able to update the props inline and have the control change is always fun. I do think some have such a large surface area of props that it can easily make the page feel overwhelming (I'm looking at you, DataTable).

I think, because of that, keeping the demoes isolated to ideal use-cases might be preferred and then launch our or redirect to a dedicated page might be the best bang for our buck.

When it comes to what a prop represents, it's analogous to a symbol override in Sketch (roughly) in that you can change text, style, variant, etc.

Would it be ok to completely hide the code by default or would you want to see it up.

I think having the code block visible at the beginning would be helpful

Where is the primary place we want users looking at component code?

Most folks look at the storybook as they tend to give the largest amount of info

Will/should this component demo replace the React sandbox?

I think it can replace if we fully document all the props, however this might mean having to recreate parts of storybook that folks find valuable. For context, folks often request our storybook stories for PALs/add-ons such that they can use them, as well.

Window will only ever show react code?

I think this would be the best bet for now.

Is the react code useful to see if you're not a react user?

Not at all 😞

[vpicone]

I think being able to edit the code block isn’t super essential, but seeing the code react to changes in props before copying it is.

I’m also on the side of showing the code by default, I don’t think there’s much to be gained from hiding it but it just adds an extra click to see the component updating every time.

[aagonzales]

Final designs for development ✅

Sketch file: https://ibm.box.com/s/u0om4lkl4u3vm9v7j9vlfq6moarqufb4

Basic spec

Theme Switcher

A content switcher at the top of the window changes the theme appearance. The background of the window also changes and has a 8px white border around the edge.

Responsive behavior

>large break point Window grows proportionally with 12 columns above large breakpoint

Medium and small breakpoints Right panel becomes collapsible/expandable and is collapsed by default. Once open panel is only collapsible by clicking the x or clicking outside of the panel.

Full page mode

By clicking the maximize arrows the component window takes over the whole page. This allows the user to have a bigger working area.

Example of other components

[vpicone]

@aagonzales could you clarify what you mean by 'state'? Is that hover/focus type interactions?

[aagonzales]

States in this context would be something that the user can't see by interacting with the component like: disabled, skeleton, invalid.

States that should just be viewed through interacting with the component itself (these don't need extras controls):

• enabled
• hover
• focus
• active

[vpicone]

@aagonzales if you have a spec a little info icon or something next to the knobs that'd be great

It could also be a dashed underline on the knob name or something maybe?

[jeanservaas]

@vpicone mike made the point that this could be a Gatsby component potentially too right?

[mjabbink]

I don’t see why not and also should be something we focus on this cycle since it has huge impact on user experience. Will also resolve some issues we currently have in Carbon when displaying a component in the demo window. But Gatsby or not we should totally rock this.

[mjabbink]

Wait a second. Isn’t the Carbon site Gatsby theme? It’s no different to BC, IDL, Design for AI, etc. I wonder if there are some components we do not want the entire Design Ecosystem to use can they be hidden? Or is that anti open source community. I’m fine either way but then I’m think it’s a Gatsby component for sure.

[mjabbink]

Can’t wait to see this in action

[mjabbink]

From what I see in above visual specs this needs adjusting so snippet goes full width under demo window and side panel