From d3d0eab356839cb91a338d4b08bb002637eed93d Mon Sep 17 00:00:00 2001 From: "Felix T.J. Dietrich" Date: Tue, 30 Jul 2024 16:27:10 +0200 Subject: [PATCH] add docs --- docs/dev/getting_started/getting_started.rst | 39 ++++++++++ docs/dev/getting_started/storybook.svg | 72 +++++++++++++++++++ .../app/ui/button/button/button.component.ts | 3 + 3 files changed, 114 insertions(+) create mode 100644 docs/dev/getting_started/storybook.svg diff --git a/docs/dev/getting_started/getting_started.rst b/docs/dev/getting_started/getting_started.rst index 87cfe463..41ece67a 100644 --- a/docs/dev/getting_started/getting_started.rst +++ b/docs/dev/getting_started/getting_started.rst @@ -84,6 +84,45 @@ Best Practices 4. **Avoid Premature Abstraction:** Don't use ``@apply`` just to clean up your HTML. **It is fine to repeat yourself!** 5. **Design Tokens:** Utilize design tokens for consistent theming and easy maintenance of your design system. Define and use them in your Tailwind configuration for colors, spacing, typography, etc. +Storybook: Component Driven UI +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +**Storybook.js is a frontend workshop for building UI components and pages in isolation.** Thousands of teams, including ours, use it for UI development, testing, and documentation. It's open source and free, and it transforms how we develop user interfaces by enabling us to focus on creating high-quality, reusable components without the grunt work. + +.. figure:: ./storybook.svg + :width: 250px + :alt: Storybook Logo + + +Storybook's Core Strengths +"""""""""""""""""""""""""" + +1. **Isolation:** Develop components in isolation, ensuring they work independently of the app. This prevents issues arising from dependencies on other components or global application state. +2. **Component-Driven Development (CDD):** Focus on building individual UI components first and then composing them into complete user interfaces. This methodology aligns with modern frontend best practices and enhances reusability and maintainability. +3. **Interactive Documentation:** Each component can be documented interactively, allowing developers and designers to see the components in various states and configurations. +4. **Automated Testing:** Storybook supports a variety of testing tools for visual regression testing, accessibility checks, and behavior testing, ensuring components meet quality standards before integration. + +Getting Started with Storybook +"""""""""""""""""""""""""""""" + +- `Storybook.js `_: Official website for Storybook. +- `Review our Storybook `_: Explore our Storybook to see an overview of our components for reference (state of ``develop`` branch). +- `Storybook Docs `_: Official documentation for Storybook. +- `What's a story? `_: Learn the basics of Storybook and how to create stories. +- `Storybook Tutorial `_: Step-by-step guide to creating a Storybook for your project. +- `Chromatic `_: Automated visual testing and review tool for Storybook that we use. +- `Addons `_: Extend Storybook's functionality with a rich ecosystem of addons for actions, accessibility, backgrounds, and more. + +Best Practices for Using Storybook +"""""""""""""""""""""""""""""""""" + +1. **Organize Stories Logically:** Group stories by component type or feature to maintain a clean and navigable Storybook. +2. **Comprehensive Stories:** Ensure each component has a story and the stories cover all meaningful states, including edge cases, to thoroughly test and document its behavior. +3. **Automated Testing Integration:** Perform visual regression testing, accessibility checks, and behavior testing in Storybook to catch issues early and ensure components meet quality standards. +4. **Visual Regression Testing:** Use Chromatic for visual regression testing for Storybook stories to catch visual bugs early and ensure consistent UI across components. Ensure you have a Chromatic account that is added to the team and you are familiar with the tool. + +.. important:: + Chromatic runs on every PR, make sure to add stories and check the visual diffs and get them approved if they are expected! Build results are located in the ``Chromatic: Run Chromatic`` CI check under ``Details`` at ``Summary``. OpenAPI: Type-Safe API Interaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/dev/getting_started/storybook.svg b/docs/dev/getting_started/storybook.svg new file mode 100644 index 00000000..7bd2113d --- /dev/null +++ b/docs/dev/getting_started/storybook.svg @@ -0,0 +1,72 @@ + + + + + + + + + + + + + + + + + + + diff --git a/webapp/src/app/ui/button/button/button.component.ts b/webapp/src/app/ui/button/button/button.component.ts index 8d3a7235..6850df1f 100644 --- a/webapp/src/app/ui/button/button/button.component.ts +++ b/webapp/src/app/ui/button/button/button.component.ts @@ -41,6 +41,9 @@ interface ButtonVariants extends VariantProps {} }) export class AppButtonComponent { class = input(''); + /** + * Text label for the button + */ variant = input('default'); size = input('default'); disabled = input(false);