# Component's Engineering Guideline This guideline aims to suggest quality requirements to our base components. Many of the already existing components does not follow a few of these requirements yet, what means we all have a lot of work to do. So, feel free to apply these standards in our existing components whenever you want. ## 1. Synced with Design team The component should follow a design doc. It's important to understand from the design perspective what patterns and rules should the component follow. With that, we have higher chances of having consistency between the mockups and our application. ## 2. Clear and lean API The component API (a.k.a. props) definition is a very sensible decision, since changing that after the componet is public would be a **breaking change**. Breaking changes raise risk of bugs and requires a significant effort to update the whole codebase with the new API and test it. It's better to create the minimum and agnostic props rather than fill the component with many of them before they are useful. We shall create new props gradually, as soon as each necessity shows up. Feature created for future scenarios is a strong symtom of over-engineering. ## 3. Be agnostic of business rules For the component to be reused over other features, it's important it to be completely decoupled of any other feature. Otherwise, multiple components solving the same problem will appear since the existing ones would be too especific. ## 4. All use cases documented in Storybook stories The documentation is key for reausage. A clear and straightforward doc brings high chances for the component to be reused by developers. In addition, the Designers can also benefit from Storybook as well, to understand the final component behavior and work on it when necessary. ## 5. Be written in TypeScrypt TypeScript helps a lot bringing clear and strong API's. Plus it enforces type consistency, which is beautiful for shared components. In addition, the Storybook is smart enough to document the component's API automatically only by reading the component's types. ## 6. Full covered with unit tests Unit tests are essential for keeping the components stable on the mid/long term. As the time pass, the code will require changes like bug fixes or enhancements, and it's quite dangerous to do it with poor or no unit tests. In addition, a good test suite also helps like a code documentation, because a good test suite can show exactly what is expected from the component to do. ## 7. Class Names ### a. The class names must be prefixed with `wk-` The class prefix works as an unique identifier, meaning the component belongs a group of standardized components, that could be seen in the codebase and even in the rendered DOM. By the way, Wk is from Works. E.g. `wk-button`, `wk-col`, `wk-row`, etc. ### b. The class names must follow BEM pattern BEM is an short of **Block, Element** and **Model**, and it is a easy and well known patter broadly used in the marked. It may looks weird at first, but it is a powerful standard that bring organization and semantic to the component's classes. E.g. `wk-drawer__header`, `wk-collapse__body--open` Read more in http://getbem.com ### c. Every component must contain a default class Even in case the component does not require a especific style, it must hold a default class name in the parent element, that also works as a component identifier. It enables the component's style to be easily extended, since a parent component can apply new styles or even modify existing styles to the component in a given and especific context. E.g. `wk-button`, `wk-select`, `wk-divider`, etc.