Merge pull request #19136 from storybookjs/chore_docs_add_why_page

Chore: (Docs)Adds why page

docs/faq.md

@@ -156,6 +156,7 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S
 
 | Section          | Page                                      | Current Location                                                                                           | Version 5.3 location                                                                                                                                                                                                                                                 | Version 5.0 location                                                                                                                                     |
 | ---------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| N/A              | Why Storybook                             | [See current documentation](./why-storybook.md)                                                            | Non existing feature or undocumented                                                                                                                                                                                                                                 | Non existing feature or undocumented                                                                                                                     |
 | Get started      | Install                                   | [See current documentation](./get-started/install.md)                                                      | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides/quick-start-guide)                                                                                                                                     | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/guides/quick-start-guide)                         |
 |                  | What's a story                            | [See current documentation](./get-started/whats-a-story.md)                                                | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides)                                                                                                                                    | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/guides)                        |
 |                  | Browse Stories                            | [See current documentation](./get-started/browse-stories.md)                                               | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/guides)                                                                                                                                    | [See versioned documentation for your framework](https://github.com/storybookjs/storybook/blob/release/5.0/docs/src/pages/guides)                        |

docs/snippets/angular/histogram-story.mdx.mdx

@@ -0,0 +1,24 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+
+import { HistogramComponent } from './histogram.component';
+
+<Meta title="Histogram" component={HistogramComponent} />
+
+export const Template = (args) => ({ props: args });
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/angular/histogram-story.ts.mdx

@@ -0,0 +1,28 @@
+```ts
+// Histogram.stories.ts
+
+import { Meta, Story } from '@storybook/angular';
+
+import { HistogramComponent } from './histogram.component';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/angular/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: HistogramComponent,
+} as Meta;
+
+const Template: Story = (args) => ({
+  props: args,
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/html/histogram-story.js.mdx

@@ -0,0 +1,23 @@
+```js
+// Histogram.stories.js
+
+import { createHistogram } from './Histogram';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/html/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+};
+
+const Template = (args) => createHistogram(args);
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/html/histogram-story.ts.mdx

@@ -0,0 +1,25 @@
+```ts
+// Histogram.stories.ts
+
+import { Meta, StoryFn } from '@storybook/html';
+
+import { Histogram, HistogramProps } from './Histogram';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/html/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+} as Meta;
+
+const Template: StoryFn<HistogramProps> = (args) => createHistogram(args);
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/preact/histogram-story.js.mdx

@@ -0,0 +1,27 @@
+```js
+// Histogram.stories.js|jsx
+
+/** @jsx h */
+import { h } from 'preact';
+
+import { Histogram } from './Histogram';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/preact/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+};
+
+const Template = (args) => <Histogram {...args} />;
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/preact/histogram-story.mdx.mdx

@@ -0,0 +1,24 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs/';
+
+import { Histogram } from './Histogram';
+
+<Meta title="Histogram" component={Histogram} />
+
+export const Template = (args) => <Histogram {...args} />;
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/react/histogram-story.js.mdx

@@ -0,0 +1,26 @@
+```js
+// Histogram.stories.js|jsx
+
+import React from 'react';
+
+import { Histogram } from './Histogram';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+};
+
+const Template = (args) => <Histogram {...args} />;
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/react/histogram-story.mdx.mdx

@@ -0,0 +1,24 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+
+import { Histogram } from './Histogram';
+
+<Meta title="Histogram" component={Histogram} />
+
+export const Template = (args) => <Histogram {...args} />;
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/react/histogram-story.ts.mdx

@@ -0,0 +1,28 @@
+```ts
+// Histogram.stories.ts|tsx
+
+import React from 'react';
+
+import { ComponentStory, ComponentMeta } from '@storybook/react';
+
+import { Histogram } from './Histogram';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+} as ComponentMeta<typeof Histogram>;
+
+const Template: ComponentStory<typeof Histogram> = (args) => <Histogram {...args} />;
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/svelte/histogram-story.js.mdx

@@ -0,0 +1,27 @@
+```js
+// Histogram.stories.js
+
+import Histogram from './Histogram.svelte';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/svelte/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+};
+
+const Template = (args) => ({
+  Component: Histogram,
+  props: args,
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/svelte/histogram-story.mdx.mdx

@@ -0,0 +1,27 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+
+import Histogram from './Histogram.svelte';
+
+<Meta title="Histogram" component={Histogram} />
+
+export const Template = (args) => ({
+  Component: Histogram,
+  props: args,
+});
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/vue/histogram-story.2.js.mdx

@@ -0,0 +1,28 @@
+```js
+// Histogram.stories.js
+
+import Histogram from './Histogram.vue';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/vue/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+};
+
+const Template = (args, { argTypes }) => ({
+  components: { Histogram },
+  props: Object.keys(argTypes),
+  template: '<Histogram v-bind="$props" v-on="$props" />',
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/vue/histogram-story.3.js.mdx

@@ -0,0 +1,30 @@
+```js
+// Histogram.stories.js
+
+import Histogram from './Histogram.vue';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/vue/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+};
+
+const Template = (args) => ({
+  components: { Histogram },
+  setup() {
+    return { args };
+  },
+  template: '<Histogram v-bind="args" />',
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/vue/histogram-story.mdx-2.mdx

@@ -0,0 +1,28 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+
+import Histogram from './Histogram.vue';
+
+<Meta title="Histogram" component={Histogram} />
+
+export const Template = (args, { argTypes }) => ({
+  components: { Histogram },
+  props: Object.keys(argTypes),
+  template: `<Histogram v-bind="$props" v-on="$props" />`,
+});
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/vue/histogram-story.mdx-3.mdx

@@ -0,0 +1,30 @@
+```md
+<!-- Histogram.stories.mdx -->
+
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+
+import Histogram from './Histogram.vue';
+
+<Meta title="Histogram" component={Histogram} />
+
+export const Template = (args) => ({
+  components: { Histogram },
+  setup() {
+    return { args };
+  },
+  template: '<Histogram v-bind="args" />',
+});
+
+<Canvas>
+  <Story
+    name="Default"
+    args={{
+      dataType: 'latency',
+      showHistogramLabels: true,
+      histogramAccentColor: '#1EA7FD',
+      label: 'Latency distribution',
+    }} >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+```

docs/snippets/vue/histogram-story.ts-2.ts.mdx

@@ -0,0 +1,30 @@
+```ts
+// Histogram.stories.ts
+
+import { Meta, StoryFn } from '@storybook/vue';
+
+import Histogram from './Histogram.vue';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/vue/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+} as Meta<typeof Histogram>;
+
+const Template: StoryFn<typeof Histogram> = (args, { argTypes }) => ({
+  components: { Button },
+  props: Object.keys(argTypes),
+  template: '<Histogram v-bind="$props" v-on="$props" />',
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/vue/histogram-story.ts-3.ts.mdx

@@ -0,0 +1,33 @@
+```ts
+// Histogram.stories.ts
+
+import { Meta, StoryFn } from '@storybook/vue3';
+
+import Histogram from './Histogram.vue';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/vue/configure/overview#configure-story-loading
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+  component: Histogram,
+} as Meta<typeof Histogram>;
+
+//👇 We create a “template” of how args map to rendering
+const Template: StoryFn<typeof Histogram> = (args) => ({
+  components: { Histogram },
+  setup() {
+    return { args };
+  },
+  template: '<Histogram v-bind="args" />',
+});
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/snippets/web-components/histogram-story.js.mdx

@@ -0,0 +1,32 @@
+```js
+// Histogram.stories.js
+
+import { html } from 'lit-html';
+
+import './histogram-component';
+
+export default {
+  /* 👇 The title prop is optional.
+   * See https://storybook.js.org/docs/web-components/configure/overview
+   * to learn how to generate automatic titles
+   */
+  title: 'Histogram',
+};
+
+const Template = ({ dataType, showHistogramLabels, histogramAccentColor, label }) => html`
+  <histogram-component
+    .dataType=${dataType}
+    .showHistogramLabels=${showHistogramLabels}
+    .histogramAccentColor=${histogramAccentColor}
+    .label=${label}
+  ></histogram-component>
+`;
+
+export const Default = Template.bind({});
+Default.args = {
+  dataType: 'latency',
+  showHistogramLabels: true,
+  histogramAccentColor: '#1EA7FD',
+  label: 'Latency distribution',
+};
+```

docs/toc.js

@@ -1,5 +1,10 @@
 module.exports = {
   toc: [
+    {
+      title: '💭 Why',
+      pathSegment: 'why-storybook',
+      type: 'link',
+    },
     {
       title: '🚀 Get started',
       pathSegment: 'get-started',

docs/why-storybook.md

@@ -0,0 +1,140 @@
+---
+title: 'Why Storybook?'
+---
+
+## The problem
+
+The web’s universality is pushing more complexity into the frontend. It began with responsive web design, which turned every user interface from one to 10, 100, 1000 different user interfaces. Over time, additional requirements piled on like devices, browsers, accessibility, performance, and async states.
+
+Component-driven tools like React, Vue, and Angular help break down complex UIs into simple components but they’re not silver bullets. As frontends grow, the number of components swells. Mature projects can contain hundreds of components that yield thousands of discrete variations.
+
+To complicate matters further, those UIs are painful to debug because they’re entangled in business logic, interactive states, and app context.
+
+The breadth of modern frontends overwhelm existing workflows. Developers must consider countless UI variations, yet aren’t equipped to develop or organize them all. You end up in a situation where UIs are tougher to build, less satisfying to work on, and brittle.
+
+![UI multiverse](./misc-docs-assets/why-storybook/multiverse.png)
+
+## The solution
+
+**Build UIs in isolation**
+
+Every piece of UI is now a [component](https://www.componentdriven.org/). The superpower of components is that you don't need to spin up the whole app just to see how they render. You can render a specific variation in isolation by passing in props, mocking data, or faking events.
+
+Storybook is packaged as a small, development-only, [workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) that lives alongside your app. It provides an isolated iframe to render components without interference from app business logic and context. That helps you focus development on each variation of a component, even the hard-to-reach edge cases.
+
+<video autoPlay muted playsInline loop>
+  <source
+    src="./misc-docs-assets/why-storybook/whats-a-story.mp4"
+    type="video/mp4"
+  />
+</video>
+
+**Capture UI variations as “stories”**
+
+When developing a component variation in isolation, save it as a story. [Stories](https://github.com/ComponentDriven/csf) are a declarative syntax for supplying props and mock data to simulate component variations. Each component can have multiple stories. Each story allows you to demonstrate a specific variation of that component to verify appearance and behavior.
+
+You write stories for granular UI component variation and then use those stories in development, testing, and documentation.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'react/histogram-story.js.mdx',
+    'react/histogram-story.ts.mdx',
+    'react/histogram-story.mdx.mdx',
+    'angular/histogram-story.ts.mdx',
+    'angular/histogram-story.mdx.mdx',
+    'vue/histogram-story.2.js.mdx',
+    'vue/histogram-story.ts-2.ts.mdx',
+    'vue/histogram-story.mdx-2.mdx',
+    'vue/histogram-story.3.js.mdx',
+    'vue/histogram-story.ts-3.ts.mdx',
+    'vue/histogram-story.mdx-3.mdx',
+    'svelte/histogram-story.js.mdx',
+    'svelte/histogram-story.mdx.mdx',
+    'web-components/histogram-story.js.mdx',
+    'preact/histogram-story.js.mdx',
+    'preact/histogram-story.mdx.mdx',
+    'html/histogram-story.js.mdx',
+    'html/histogram-story.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+**Storybook keeps track of every story**
+
+Storybook is an interactive directory of your UI components and their stories. In the past, you'd have to spin up the app, navigate to a page, and contort the UI into the right state. This is a huge waste of time and bogs down frontend development. With Storybook, you can skip all those steps and jump straight to working on a UI component in a specific state.
+
+<video autoPlay muted playsInline loop>
+  <source
+    src="./misc-docs-assets/why-storybook/7.0-storybook-hero-video.mp4"
+    type="video/mp4"
+  />
+</video>
+
+<details>
+<summary>Where does Storybook fit into my project?</summary>
+
+Storybook is packaged as a small, development-only, [workshop](https://bradfrost.com/blog/post/a-frontend-workshop-environment/) that lives alongside your app. Install it by [running a command](./get-started/install.md).
+
+During development, run it in a separate node process. If you’re working on UI in isolation, the only thing you’ll need to run is Storybook.
+
+</details>
+
+<details>
+<summary>Does Storybook work with X?</summary>
+
+Storybook aims to integrate with industry-standard tools and platforms to simplify setup. Thanks to our ambitious developer community, we’ve made significant progress. There are hundreds of [addons](https://storybook.js.org/addons/) and tutorials that walk through how to set up Storybook in all types of projects.
+
+If you’re using a niche framework or a recently launched tool, we might not have an integration for it yet. Consider creating a [proof of concept](./addons/writing-addons.md) yourself first to lead the way for the rest of the community.
+
+</details>
+
+<details>
+<summary>What’s the recommended Storybook workflow?</summary>
+
+Every team is different and so is their workflow. Storybook is designed to be incrementally adoptable. Teams can gradually try features to see what works best for them.
+
+Most community members choose a [Component-Driven](https://www.componentdriven.org/) workflow. UIs are developed in isolation from the “bottom up” starting with basic components then progressively combined to assemble pages.
+
+1. Build each component in isolation and write stories for its variations.
+2. Compose small components together to enable more complex functionality.
+3. Assemble pages by combining composite components.
+4. Integrate pages into your project by hooking up data and business logic.
+
+</details>
+
+## Benefits
+
+When you write stories for components, you get a bunch of additional benefits for free.
+
+**📝 Develop UIs that are more durable**
+
+Isolate components and pages and track their use cases as [stories](./writing-stories/introduction.md). Verify hard-to-reach edge cases of UI. Use addons to mock everything a component needs—context, API requests, device features, etc.
+
+**✅ Test UIs with less effort and no flakes**
+
+Stories are a pragmatic, reproducible way of tracking UI states. Use them to spot-test the UI during development. Storybook offers built-in workflows for automated [Accessibility](./writing-tests/accessibility-testing.md), [Interaction](./writing-tests/interaction-testing.md), and [Visual](./writing-tests/visual-testing.md) testing. Or use stories as test cases by importing them into other JavaScript testing tools.
+
+**📚 Document UI for your team to reuse**
+
+Storybook is the single source of truth for your UI. Stories index all your components and their various states, making it easy for your team to find and reuse existing UI patterns. Storybook also auto-generates [documentation](./writing-docs/introduction.md) from those stories.
+
+**📤 Share how the UI actually works**
+
+Stories show how UIs actually work, not just a picture of how they're supposed to work. That keeps everyone aligned on what's currently in production. [Publish Storybook](./sharing/publish-storybook.md) to get sign-off from teammates. Or [embed](./sharing/embed.md) them in wikis, Markdown, and Figma to streamline collaboration.
+
+**🚦Automate UI workflows**
+
+Storybook is compatible with your continuous integration workflow. Add it as a CI step to automate user interface testing, review implementation with teammates, and get signoff from stakeholders.
+
+## Write stories once, reuse everywhere
+
+Storybook is powered by [Component Story Format](https://github.com/ComponentDriven/csf), an open standard based on JavaScript ES6 modules. This enables stories to interoperate between development, testing, and design tools. Each story is exported as a JavaScript function enabling you to reuse it with other tools. No vendor lock-in.
+
+Reuse stories with [Jest](https://jestjs.io/) and [Testing Library](https://testing-library.com/) to verify interactions. Put them in [Chromatic](https://www.chromatic.com/) for visual testing. Audit story accessibility with [Axe](https://github.com/dequelabs/axe-core). Or test user flows with [Playwright](https://playwright.dev/) and [Cypress](https://www.cypress.io/). Reuse unlocks more workflows at no extra cost.
+
+---
+
+Storybook is purpose-built to help you develop complex UIs faster with greater durability and lower maintenance. It’s used by 100s of [leading companies](https://storybook.js.org/showcase) and thousands of [developers](https://github.com/storybookjs/storybook/).