From 2b6084636e6c2d9c21a64e634f3448ca49dfad95 Mon Sep 17 00:00:00 2001 From: "Felix T.J. Dietrich" Date: Tue, 30 Jul 2024 11:47:28 +0200 Subject: [PATCH 1/3] link storybook in readme --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cf85b88b..3c18a371 100644 --- a/README.md +++ b/README.md @@ -11,4 +11,6 @@ Hephaestus leverages generative AI, specifically large language models (LLMs), t Hephaestus /hɪˈfɛstəs/ is the Greek god of blacksmiths, craftsmen, and artisans, symbolizing the fusion of creativity and technical skill. ## Documentation -The documentation can be found [here](https://ls1intum.github.io/Hephaestus/). + +Technical/user docs: [Read the Docs](https://ls1intum.github.io/Hephaestus/) +UI component docs: [Storybook](https://develop--66a8981a27ced8fef3190d41.chromatic.com/) \ No newline at end of file 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 2/3] 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); From 43c4410f85ad5edf05835d8800e116c1216955f7 Mon Sep 17 00:00:00 2001 From: "Felix T.J. Dietrich" Date: Tue, 30 Jul 2024 16:42:25 +0200 Subject: [PATCH 3/3] add tip --- docs/dev/getting_started/getting_started.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/dev/getting_started/getting_started.rst b/docs/dev/getting_started/getting_started.rst index 41ece67a..00de2e58 100644 --- a/docs/dev/getting_started/getting_started.rst +++ b/docs/dev/getting_started/getting_started.rst @@ -124,6 +124,9 @@ Best Practices for Using Storybook .. 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``. +.. tip:: + Refer to `Shadcn/ui `_ (React components) for theming and component examples. We are copying their styles and also use `Class Variance Authority `_ for our components like them. The Shadcn/ui Angular port `Spartan/ui `_ can also be used as reference, they are also using Storybook but we are not directly copying their components' code. Refer to existing components in the project for `examples `_. For more complex components, we might want to use `Angular CDK `_ as a base while avoiding libraries that are not widely used or maintained. + OpenAPI: Type-Safe API Interaction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^