From cf536e0bbef06b02c9899c7751ed85c2324a6ee5 Mon Sep 17 00:00:00 2001 From: angsherpa456 Date: Mon, 26 Feb 2024 11:39:27 +0100 Subject: [PATCH] docs(general):Update ARCHITECTURE.md file --- README.md | 4 +++ docs/ARCHITECTURE.md | 78 +++++++++++++++++++++++++++++++++++++------- docs/TESTING.md | 16 +++++---- 3 files changed, 80 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f2d15332d..c8dfe6cb2 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ - [Questions, feedback or feature requests?](#questions-feedback-or-feature-requests) - [Report an issue](#report-an-issue) - [:gear: Requirements](#gear-requirements) + - [:triangular_ruler: Architecture](#triangular_ruler-architecture) - [:rocket: How to start](#rocket-how-to-start) - [Installation](#installation) - [Setup](#setup) @@ -71,6 +72,9 @@ We are happy about anyone who wants to participate in our community. To ask ques ### Report an issue Please let us know in case you are finding any bugs by reporting them with our [bug report template](https://github.com/deven-org/B01LER-Kitchen/issues/new?assignees=&labels=%F0%9F%9A%A8+new%3A%3Abug&projects=deven-org%2F3&template=1_bug_report.yaml&title=%5BBug%5D%3A+). The template can also be used to report issues with our documentation. In case you discover a security vulnerability please review our [security policy](/docs/SECURITY.md) for more details on how to report it. +## :triangular_ruler: Architecture +Get to know about our Architecture [here](./docs/ARCHITECTURE.md). + ## :gear: Requirements 1. First you need to install Git. Git is needed to clone the project to your local machine. If you don't have it installed yet you can follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). 2. This project is a Node.js package. You need Node Version 18 or higher in order to run it. Check your installed version with node -v. For more information check out the [Node.js Documentation](https://nodejs.org/en/docs/). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 5c44ca22d..4e56d7b2b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,24 +1,80 @@ # Architecture -This chapter should provide the user with as mutch information as possible about the architecture and overall structure of your project. Please provide a short introduction here. +The BO1LER, a fully customisable design system (DS), is developed using the [Lit](https://lit.dev/docs/) template and Figma. The design system serves as a core unit for UI components, styles, and guidelines, ensuring consistency and efficiency across our applications. ## Content - [Architecture](#architecture) - [Content](#content) - [Overall Structure](#overall-structure) + - [File Structure](#file-structure) + - [Version Control](#version-control) + - [Documentation and Testing](#documentation-and-testing) + - [CI/CD](#ci-cd) - [Technical Decisions](#technical-decisions) - - [APIs](#apis) + - [Web Components](#web-components) + - [Styles](#styles) + - [Guidelines](#guidelines) + - [Figma](#figma) + - [Contributing](#contributing) ## Overall Structure -Please explain the overall structure of your project and how everything works together. You can use screenshots or code snippets to help visualize things like e.g. your folder structure or the project setup. In this chapter you can be as detailed as you like. +The entire code is developed in TypeScript, which facilitates type checking and offers additional functionalities for detecting errors early in the development process. Besides configuration files, the 'Packages' directory holds essential content. Within this directory are subfolders named according to their contents. + +### File Structure +Our project has the following file structure: + + └── .github // GitLab CI/CD pipeline + └── .husky // Git hooks configuration files and scripts + └── .vscode // VS code extensions and settings json + └── .yarn // Yarn releases folder + └── docs // Includes documentation about Contributing, Code of Conduct, etc. + └── packages + └── assets // Collection of resources, such as images and other files utilized in B01LER + └── eslint-config-boiler // Specific ESLint configuration for this project + └── figma-design-tokens // Design tokens configuration files and exported token json files + └── icons // Icon configuration files and a collection of icon files in svg format + └── js-example-app // Source code for js testing app for B01LER DS + └── ui-library + └── .storybook // Configuration files for Storybook environment, assets, fonts and theme + └── src + └── components // Collection of individual B01LER DS components + └── foundation // Collection of generated token files and component and semantic tokens + └── globals // Exports of constants and types + └── util // Collection of utility or helper functions + └── LICENSE.md // Software license that governs the use, distribution, and modification of B01LER + └── README.md // Introductory documentation for B01LER + +We also provide example applications for [Vanilla JS](https://b01ler.onrender.com/js-example-app) located in 'js-example-app'. + +The 'ui-library' directory encompasses all UI components, along with their corresponding test and index files for Storybook. Storybook serves as a development environment tool, providing a sandbox for independent construction and evaluation of components. Operating separately from the application, [Storybook](https://b01ler.onrender.com/) ensures that component behavior remains consistent, irrespective of project dependencies. + +Regarding Figma tokens, the 'figma-design-token' directory contains all design system components utilized in token generation. Configuration for token generation can be found within the same folder. The generated tokens are stored and utilized directly within the 'ui-library'. + +### Version Control +The code base, hosted on GitHub and maintained by the Deven team, is publicly accessible, inviting interested users to contribute to the ongoing development and maintenance efforts of the project. We encourage collaboration and welcome feedback from the community to enhance the project's capabilities and ensure its continued evolution. + +### Documentation and Testing +The project adheres to best practices for documentation, and testing. The codebase is thoroughly documented with live preview capability and explicit guidelines on usage and contribution procedures. Additionally, comprehensive component tests are integrated to verify that modifications uphold the project's integrity and functionality, preventing regressions or defects from emerging. + +### CI-CD +The changes made in project's code base adheres to a continuous integration and delivery (CI/CD) pipeline. This guarantees that any alterations undergo rigorous testing and validation before being released to the production environment. ## Technical Decisions -In this section you should list all technical things you use like frameworks, tools, languages and provide explanations of why you have choosen them. Think about e.g. what are the main reasons you choose a framework, what are the advatages you need for your project? Try to be as clear as possible so also new joiners understand why your setup is the best for your project. +This section lists all technical decisions. It includes explanations of the frameworks, tools and languages that are used in the project. It also includes the main reasons for these decisions. + +### Web Components +Our design system includes a wide range of reusable UI components, each carefully designed and implemented using the [Lit](https://lit.dev/docs/) template. These web components cover various aspects of our application's user interface, including buttons, input fields, tab bars, divider, and more. The reason for using Lit was that it being a straightforward library designed for constructing rapid, lightweight web components. Furthermore, it provides the developers a component base class that eliminates boilerplate code, offering reactive state, scoped styles, and a declarative template system. This system is characterized by its compact size, swift performance, and expressive nature. + +### Styles +The design system provides a comprehensive set of styles, including typography, colors, spacing, and layout guidelines. These styles are meticulously crafted to maintain visual coherence and enhance the overall user experience. + +### Events +The various events, such as focus, blur, click, etc., have the 'blr' prefix appended, allowing them to be accessed as 'blrFocus,' 'blrBlur,' 'blrClick,' and so on. One example can be seen in [Storybook documentation](https://b01ler.onrender.com/). + +### Guidelines +In addition to components and styles, the design system includes detailed guidelines and best practices for design and development. These guidelines cover topics such as accessibility, responsive design, interaction patterns, and naming conventions, empowering our team to create consistent and high-quality user interfaces. -## APIs -Please describe briefly how you manage the APIs of your project and how to use them. +### Figma +Figma plays an essential role in our product development, as B01LER relies heavily on its functionalities. It serves as the platform for our design assets, including the component designs. Moreover, we utilize the [tokens studio plugin](https://www.figma.com/community/plugin/843461159747178978) within Figma to manage and update our design tokens effectively. Figma allows our team to create, share, and collaborate on designs in real-time, streamlining the design process and facilitating cross-functional collaboration. -The documentation could: - - describe the data structures, functions, arguments, return types, classes, payloads, etc., developers can refer to. - - refer to other existing resources (git repos, websites, etc.) - - if you are using one or more tools, describe how to install / access / use them - - how to test the APIs locally +## Contributing +Contributions to the design system are welcome! If you have suggestions for new components, styles, or guidelines, please open an issue or submit a pull request. Your contributions help improve the consistency and quality of our user interfaces. Before opening a [bug report](https://github.com/deven-org/B01LER-Kitchen/issues/new?assignees=&labels=%F0%9F%9A%A8+new%3A%3Abug&projects=deven-org%2F3&template=1_bug_report.yaml&title=%5BBug%5D%3A+) or a [feature request](https://github.com/deven-org/B01LER-Kitchen/issues/new?assignees=&labels=%F0%9F%9A%A8+new%3A%3Aenhancement&projects=deven-org%2F3&template=2_feature_request.yaml&title=%5BFeature+Request%5D%3A+) please check out our [contribution guide](CONTRIBUTING.md) and our [code of conduct](CODE_OF_CONDUCT.md). In case you discover a security vulnerability please review our [security policy](SECURITY.md) for more details on how to report it. diff --git a/docs/TESTING.md b/docs/TESTING.md index 5392ac4dd..2b16ee569 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -5,12 +5,12 @@ This chapter provides the user with all needed information around testing within - [Testing](#testing) - [Content](#content) - [Different kind of tests](#different-kind-of-tests) - - [Testing strategy](#testing-strategy) + - [Testing Strategy](#testing-strategy) - [Tooling](#tooling) - - [open-wc-testing](#open-wc-testing) + - [open-wc-testing](#open-wc-testing) - [How to write tests](#how-to-write-tests) - - [Directory structure](#directory-structure) - - [Examples](#examples) + - [Directory Structure](#directory-structure) + - [Examples](#examples) - [How to run tests](#how-to-run-tests) - [Contributing](#contributing) @@ -19,21 +19,23 @@ Component test - It ensures that each component render correctly and respond to In future other testing types like Integration Testing, Performance Testing can be added in the Continuous Integration process. -## Testing strategy +## Testing Strategy The tests are crafted to validate the functionality of the software, ensuring it operates as designed and identifying bugs and errors before they are deployed to production. Testing serves as a proactive measure to identify issues early in the development phase. Our objective is to create component test for each individual component within the codebase, guaranteeing their intended functionality and preventing regressions from new changes. ## Tooling ### open-wc-testing -This repository contains tests written using the `@open-wc/testing` library. `@open-wc/testing` provides a suite of tools and utilities for testing web components, following modern best practices and standards. +This repository contains tests written using the `@open-wc/testing` library. `@open-wc/testing` provides a suite of +tools and utilities for testing web components, following modern best practices and standards. [Read more here](https://open-wc.org/docs/testing/testing-package/). ## How to write tests To write tests using `@open-wc/testing`, follow these steps: + 1. Import the necessary functions and utilities from `@open-wc/testing`. 2. Write your test cases using the provided utilities such as `fixture`, `html`, `litFixture`, etc. -### Directory structure +### Directory Structure - `src/components/`: Contains the source code of the components and respective test for it. ### Examples