browser/libs/components/src/stories/introduction.mdx

import { Meta } from "@storybook/addon-docs";

<Meta title="Documentation/Introduction" />

<style>
  {`
  .subheading {
    --mediumdark: '#999999';
    font-weight: 900;
    font-size: 13px;
    color: #999;
    letter-spacing: 6px;
    line-height: 24px;
    text-transform: uppercase;
    margin-bottom: 12px;
    margin-top: 40px;
  }

  .link-list {
    display: grid;
    grid-template-columns: 1fr;
    grid-template-rows: 1fr;
    row-gap: 10px;
  }

  @media (min-width: 620px) {
    .link-list {
      row-gap: 20px;
      column-gap: 20px;
      grid-template-columns: 1fr 1fr;
    }
  }

  @media all and (-ms-high-contrast:none) {
  .link-list {
      display: -ms-grid;
      -ms-grid-columns: 1fr 1fr;
      -ms-grid-rows: 1fr 1fr;
    }
  }

  .link-item {
    display: block;
    padding: 20px 30px 20px 15px;
    border: 1px solid #00000010;
    border-radius: 5px;
    transition: background 150ms ease-out, border 150ms ease-out, transform 150ms ease-out;
    color: #333333;
    display: flex;
    align-items: flex-start;
  }

  .link-item:hover {
    border-color: #1EA7FD50;
    transform: translate3d(0, -3px, 0);
    box-shadow: rgba(0, 0, 0, 0.08) 0 3px 10px 0;
  }

  .link-item:active {
    border-color: #1EA7FD;
    transform: translate3d(0, 0, 0);
  }

  .link-item strong {
    font-weight: 700;
    display: block;
    margin-bottom: 2px;
  }

  .link-item img {
    height: 40px;
    width: 40px;
    margin-right: 15px;
    flex: none;
  }

  .link-item span {
    font-size: 14px;
    line-height: 20px;
  }
  `}
</style>

# Bitwarden Component Library

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 usage of the CL is in the web-based clients, namely _web_, _browser_, and
_desktop_.

**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)

---

<div className="subheading">References</div>

<div className="link-list">
  <a className="link-item" href="https://tailwindcss.com/" target="_blank">
    <span>
      <strong>Tailwind</strong>
      The Component Library CSS is powered by the Tailwind CSS framework
    </span>
  </a>
  <a className="link-item" href="https://angular.dev/overview" target="_blank">
    <span>
      <strong>Angular</strong>
      We use Angular to build our client apps and Component Library
    </span>
  </a>
  <a className="link-item" href="https://storybook.js.org/docs" target="_blank">
    <span>
      <strong>Storybook</strong>
      Learn more about Storybook and view its implementation docs
    </span>
  </a>
  <a className="link-item" href="https://www.markdownguide.org/cheat-sheet/" target="_blank">
    <span>
      <strong>Markdown</strong>
      Quick cheatsheet for writing markdown, which is used for our Storybook docs files
    </span>
  </a>
</div>