Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise "Playground" story approach in the @carbon/react storybook #16816

Open
tay1orjones opened this issue Jun 18, 2024 · 2 comments · May be fixed by #18250
Open

Revise "Playground" story approach in the @carbon/react storybook #16816

tay1orjones opened this issue Jun 18, 2024 · 2 comments · May be fixed by #18250
Assignees
Labels
package: @carbon/react @carbon/react proposal: open This request has gone through triaging. We're determining whether we take this on or not. type: enhancement 💡
Milestone

Comments

@tay1orjones
Copy link
Member

tay1orjones commented Jun 18, 2024

Context

As a developer using @carbon/react,
I need a way to copy and paste valid/working component code snippets from storybook,
So that I can get a jumpstart using a component in my project, experiment in a sandbox/stackblitz, etc.

The @carbon/react storybook has supported this use case so far via the storysource plugin. It displays the code source of the current story being shown in the canvas. It meets this need fairly well if the story uses explicit values within the story.

Click to expand example

CleanShot 2024-06-18 at 13 42 30@2x

Although when controls/args are used, the source code doesn't work well for copy/paste because it contains storybook-specific code (...args) that would cause an error in any environment outside of our storybook:

Click to expand example

CleanShot 2024-06-18 at 13 38 46@2x

As-is experience

To combat this we have so far tried to follow a strategy where we only use controls/args on a single specific story named "Playground". Each component typically has one - controls are fully enabled, and other stories have explicit prop usage instead of controls. This way the story source is copy/paste-able for every story except the Playground story.

In some cases Playground stories can't be used because the component has variants that require different stories and aren't able to be contained in one Playground story. Button and StructuredList are an example of this currently. In these cases controls are enabled on every story and there is no Playground story.

This strategy and it's inconsistency is confusing for both maintainers and users of the storybook.

Proposal

Stories are intended to be authored using args. Every story should be updated to use args where possible. We could then delete the playground stories.

Another way to think about this is that we're renaming Playground stories to be Default. The goal isn't to encourage adding a new story for every variant of a component - instead this change encourages further reduction of stories towards greater reliance on args.

There are a few ways we can continue supporting the copy/paste use case:

  • Enhance our docs pages to include Source or Canvas blocks, which appear to support dynamic code snippet generation when using args via the type option:
    • dynamic: Renders the story source with dynamically updated arg values

  • Provide an "Open in Stackblitz" link on every story via the stackblitz addon, where the current story source can be opened in a sandbox for experimentation

Additional benefits of this approach include:

  • Having one less story in every component folder
  • A simplified story authoring experience that would match the storybook documentation
  • Every story would support args, so we could use args for configuration in AVT and VRT tests, which would simplify the "arrange" portion of these tests
@github-project-automation github-project-automation bot moved this to Triage in Roadmap Jun 18, 2024
@tay1orjones tay1orjones added the proposal: open This request has gone through triaging. We're determining whether we take this on or not. label Jun 18, 2024
@tay1orjones tay1orjones moved this to 🪆 Needs Refined in Design System Jun 18, 2024
@tay1orjones tay1orjones moved this from Triage to Icebox in Roadmap Jun 18, 2024
@tay1orjones tay1orjones moved this from Icebox to Triage in Roadmap Jun 18, 2024
@carbon-design-system carbon-design-system deleted a comment from github-actions bot Jun 18, 2024
@sstrubberg sstrubberg moved this from Triage to Icebox in Roadmap Jun 19, 2024
@sstrubberg
Copy link
Member

I freaking love quality of life improvements like this. Let's figure out a way to slide this in. Might be a fun EOY project.

@tay1orjones
Copy link
Member Author

Agree! It's kind of related to #12947, probably something to do alongside it actually.

@tay1orjones tay1orjones moved this from Icebox to Later in Roadmap Jun 20, 2024
@tay1orjones tay1orjones added this to the 2024 Q4 milestone Jun 20, 2024
@sstrubberg sstrubberg moved this from Later to Icebox 🧊 in Roadmap Sep 11, 2024
@tay1orjones tay1orjones added the package: @carbon/react @carbon/react label Oct 9, 2024
@guidari guidari self-assigned this Nov 28, 2024
@guidari guidari moved this to ⏱ Backlog in Design System Dec 2, 2024
@guidari guidari moved this from ⏱ Backlog to 🏗 In Progress in Design System Dec 2, 2024
@guidari guidari linked a pull request Dec 12, 2024 that will close this issue
@guidari guidari moved this from 🏗 In Progress to 🚦 In Review in Design System Dec 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
package: @carbon/react @carbon/react proposal: open This request has gone through triaging. We're determining whether we take this on or not. type: enhancement 💡
Projects
Status: 🚦 In Review
Status: Later 🧊
Development

Successfully merging a pull request may close this issue.

3 participants