From a5abbecf39bb17433b5b007e075de1e891efa9e5 Mon Sep 17 00:00:00 2001
From: Danielle Flinn <43477473+danielleflinn@users.noreply.github.com>
Date: Tue, 18 Oct 2022 07:54:27 -0700
Subject: [PATCH] Storybook docs structure (#3755)

* updated naming of common to documentation

* Add button docs

* updated sort order

Documentation is now above the component library and allows the general pages to come before the component specific ones.

* fixed typos

* updated file name

* fixed typo in introduction.stories.mdx

* updated banner.stories.mdx to match new docs structure

* remove plural in button docs
---
 .storybook/preview.js                         |  5 ++
 .../src/stories/Introduction.stories.mdx      |  4 +-
 ...er.stories.mdx => banner-docs.stories.mdx} |  2 +-
 .../src/stories/button-docs.stories.mdx       | 73 +++++++++++++++++++
 .../components/src/stories/colors.stories.mdx |  2 +-
 libs/components/src/stories/icons.stories.mdx |  2 +-
 6 files changed, 83 insertions(+), 5 deletions(-)
 rename libs/components/src/stories/{banner.stories.mdx => banner-docs.stories.mdx} (97%)
 create mode 100644 libs/components/src/stories/button-docs.stories.mdx

diff --git a/.storybook/preview.js b/.storybook/preview.js
index 8bc2510a08..754e8d2b88 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -12,6 +12,11 @@ export const parameters = {
       date: /Date$/,
     },
   },
+  options: {
+    storySort: {
+      order: ["Documentation", ["Introduction", "Colors", "Icons"], "Component Library"],
+    },
+  },
   docs: { inlineStories: true },
 };
 
diff --git a/libs/components/src/stories/Introduction.stories.mdx b/libs/components/src/stories/Introduction.stories.mdx
index 7b175b415d..f9cc381398 100644
--- a/libs/components/src/stories/Introduction.stories.mdx
+++ b/libs/components/src/stories/Introduction.stories.mdx
@@ -1,6 +1,6 @@
 import { Meta } from "@storybook/addon-docs";
 
-<Meta title="Common/Introduction" />
+<Meta title="Documentation/Introduction" />
 
 <style>{`
   .subheading {
@@ -86,7 +86,7 @@ developers to work more efficiently. The primary goal is to ensure a consistent
 different clients and platforms. Currently the primary focus is the web based clients, namely _web_, _browser_ and
 _desktop_.
 
-**Role out status:** we are currently in the process of transitioning the Web Vault to utilize the component library
+**Roll out status:** we are currently in the process of transitioning the Web Vault to utilize the component library
 and the other clients will follow once this work is completed.
 
 <div className="subheading">Configure</div>
diff --git a/libs/components/src/stories/banner.stories.mdx b/libs/components/src/stories/banner-docs.stories.mdx
similarity index 97%
rename from libs/components/src/stories/banner.stories.mdx
rename to libs/components/src/stories/banner-docs.stories.mdx
index 98e14ef047..7459a5ddf3 100644
--- a/libs/components/src/stories/banner.stories.mdx
+++ b/libs/components/src/stories/banner-docs.stories.mdx
@@ -1,6 +1,6 @@
 import { Meta, Story } from "@storybook/addon-docs";
 
-<Meta title="Common/Banner" />
+<Meta title="Documentation/Banner" />
 
 # Banner
 
diff --git a/libs/components/src/stories/button-docs.stories.mdx b/libs/components/src/stories/button-docs.stories.mdx
new file mode 100644
index 0000000000..0c40e78077
--- /dev/null
+++ b/libs/components/src/stories/button-docs.stories.mdx
@@ -0,0 +1,73 @@
+import { Meta, Story, Source } from "@storybook/addon-docs";
+
+<Meta title="Documentation/Button" />
+
+# Button
+
+Use buttons for actions in forms, dialogs, and more with support for style, block, icon, and state.
+
+For pairings in the bottom left corner of a page or component, the `primary` call to action will go on the left side of a button group with the `secondary` call to action option on the left.
+
+Pairings in the top right corner of a page, should have the `primary` call to action on the right.
+
+Groups of buttons should have 1rem of spacing between them.
+
+## Choosing the `<a>` or `<button>`
+
+Buttons can use either the `<a>` or `<button>` tags. Choose which based on the action the button takes:
+
+- If navigating to a new page, use `<a>`
+- If taking an action on the current page use `<button>`
+- If the button launches a dialog, use `<button>`
+
+## Submit and async actions
+
+Both submit and async action buttons use a loading button state while an action is taken.
+
+<Story id="component-library-button--loading" />
+
+If your button is preforming a long running task in the background like a server API call, be sure to review the [Async Actions Directive](https://components.bitwarden.com/?path=/story/component-library-async-actions-overview--page).
+
+## Styles
+
+There are 3 main styles for the button: Primary, Secondary, and Danger.
+
+### Primary
+
+<Story id="component-library-button--primary" />
+
+Use the primary button styling for all Primary call to actions. An action is "primary" if it relates to the main purpose of a page. There should never be 2 primary styled buttons next to each other.
+
+### Secondary
+
+<Story id="component-library-button--secondary" />
+
+The secondary styling should be used for secondary calls to action. An action is "secondary" if it relates indirectly to the purpose of a page. There may be multiple secondary buttons next to each other; however, generally there should only be 1 or 2 calls to action per page.
+
+### Danger
+
+<Story id="component-library-button--danger" />
+
+Use the danger styling only in settings when the user may preform a permanent action.
+
+## Disabled UI
+
+Both the disabled and loading states use the default state’s color with a 60% opacity or `tw-opacity-60`.
+
+<Story id="component-library-button--disabled" />
+
+## Block
+
+Typically button widths expand with thier text. In some causes though buttons may need to be block where the width is fixed and the text wraps to 2 lines if exceeding the button’s width.
+
+<Story id="component-library-button--block" />
+
+## Accessibility
+
+### Color contrast
+
+All button styles are WCAG compliant when displayed on `background` and `background-alt` colors. To use a button on a different background, double check that the color contrast is sufficient in both the light and dark themes.
+
+### Loading Buttons
+
+Include an `aria-label` attribute that defaults to “loading” but can be configurable per implementation. On click, the screen reader should announce the `aria-label`. Once the action is compelted, use another messaging pattern to alert the user that the action is complete (example: success toast).
diff --git a/libs/components/src/stories/colors.stories.mdx b/libs/components/src/stories/colors.stories.mdx
index 2daaa0325d..bdcfc13c6b 100644
--- a/libs/components/src/stories/colors.stories.mdx
+++ b/libs/components/src/stories/colors.stories.mdx
@@ -1,6 +1,6 @@
 import { Meta } from "@storybook/addon-docs";
 
-<Meta title="Common/Colors" />
+<Meta title="Documentation/Colors" />
 
 export const Row = (name) => (
   <tr class="tw-h-16">
diff --git a/libs/components/src/stories/icons.stories.mdx b/libs/components/src/stories/icons.stories.mdx
index 8ff0b2de80..3b401695ee 100644
--- a/libs/components/src/stories/icons.stories.mdx
+++ b/libs/components/src/stories/icons.stories.mdx
@@ -2,7 +2,7 @@
 
 import { Meta } from "@storybook/addon-docs/";
 
-<Meta title="Common/Icons" />
+<Meta title="Documentation/Icons" />
 
 # Iconography