From a408990a3cf0d63dba4b0ba72b63e1d08deed004 Mon Sep 17 00:00:00 2001 From: Vicki League Date: Mon, 5 May 2025 13:28:13 -0400 Subject: [PATCH] [CL-248] Update Storybook intro docs (#14253) * [CL-248] Update Storybook intro docs * add common edge cases * more updates --- libs/components/src/stories/introduction.mdx | 142 ++++++++++++++----- 1 file changed, 105 insertions(+), 37 deletions(-) diff --git a/libs/components/src/stories/introduction.mdx b/libs/components/src/stories/introduction.mdx index f533923150e..eb7328cd76d 100644 --- a/libs/components/src/stories/introduction.mdx +++ b/libs/components/src/stories/introduction.mdx @@ -83,54 +83,122 @@ import { Meta } from "@storybook/addon-docs"; # Bitwarden Component Library -The Bitwarden Component Library is a collection of reusable low level components which empowers +The Bitwarden Component Library (CL) is a collection of reusable low-level components that empower designers and developers to work more efficiently. The primary goal is to ensure a consistent design -and behavior across the different clients and platforms. Currently the primary focus is the web -based clients, namely _web_, _browser_ and _desktop_. +and behavior across the different clients and platforms. -**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. +Currently the primary usage of the CL is in the web-based clients, namely _web_, _browser_, and +_desktop_. -
Configure
+**Rollout status:** The web vault and browser extension are transitioned to use the component +library. We are currently working on the desktop application, which has the CL available for use but +is not fully migrated. + +## Components vs CSS + +We use Angular components rather than reusable CSS classes to build the Component Library. In +addition to standardizing styles, this has the benefit of standardizing DOM hierarchy, +accessibility, and usage patterns, which cannot be enforced with CSS styles alone. + +We use Tailwind to power the Component Library styles, and to build other non-CL presentational UI +elements. Teams implementing custom UIs will use a mixture of Tailwind and CL components. + +Bootstrap is deprecated. Do not introduce any new Bootstrap code to any client apps. + +## Storybook Guide + +This Storybook contains both Component Library components and team-owned components. + +Team-owned components are higher-level components that may be reused in some places in the client +apps, but are not in the Component Library because they either are not low-level enough to be +considered, or have not yet been used in enough places to be pulled into the Component Library. +These components are still important to represent in Storybook so that we can show existing +implementations, identify common patterns, and catch regressions through snapshot testing. + +### How to use Storybook to develop code + +Each component contains a documentation page and story examples. The documentation page contains +context and code snippets that will help developers learn how and why to use a given component. The +story examples show variants and common use cases visually, and their code can be referenced as +examples for implementation. + +Please note that code snippets and examples may not be production-ready, i.e. they may be missing +required properties or container-level styling. + +### When to add to Storybook + +The more components that we can represent in Storybook, the better snapshot regression coverage we +will have! Consider adding a story to Storybook when: + +- A regression is identified for a common component usage that is not currently represented in + Storybook (to prevent future regressions!) +- A new team-owned component is added to the codebase +- A team-owned component is updated and/or is being used in new places +- A new CL component is added to the codebase -- Storybook representation is a requirement for all + CL components + +Adding to the docs pages is also helpful. Consider contributing when: + +- More context / instruction would have been helpful to you as you implement a component +- A typo or error is identified in the docs + +### How to add to Storybook + +The process to add to Storybook is mostly the same for CL components and team-owned components. +Reference existing stories as examples. As you determine what content should be included, think of +what would be helpful to you if you were consuming this component for the first time. + +1. Add an mdx and story file in the same directory as the component (you can reference existing + files -- search for `*.stories.ts` and view their associated `.mdx` pages) +2. (For team-owned components) Check if your file path is already included in the + `.storybook/main.ts` config -- if not, add it +3. Write the docs `*.mdx` page + + - What is the component intended to be used for? + - How to import and use it? What inputs and slots are available? + - Are there other usage guidelines, such as pointing out similar components and when to use each? + Do's and don'ts, such as keeping content succint? + - Any accessibility or other implementation considerations? + - Does it need to be used in conjunction with any other existing components? + +4. Add stories to the `*.stories.ts` file + - Default normal use case, including variants if applicable + - Other common use cases / patterns + - Edge cases (examples below, not a comprehensive list): + - Long text -- does it truncate, ellipse, wrap, scroll, etc? + - Disabled state? + - What would it look like with an icon? + - Is there a loading state? + - You'll need to mock any services required for the component (team-owned components often have + more of this mocking to do) + +--- + +
References
Tailwind - The component library CSS is powered by the Tailwind CSS framework + The Component Library CSS is powered by the Tailwind CSS framework - + - Data - Providers and mocking for data libraries - - -
- -
Learn
- -
- - - Storybook documentation - Configure, customize, and extend - - - - - In-depth guides - Best practices from leading teams + Angular + We use Angular to build our client apps and Component Library + + + + + Storybook + Learn more about Storybook and view its implementation docs + + + + + Markdown + Quick cheatsheet for writing markdown, which is used for our Storybook docs files