Development Guidelines
Best practices & development guidelines for working with Contorion shop's frontend.
About this guide
Styling - scss/sass
CSS Naming
We use ABEM '{granularity}-{Block Name}__{Element Name}--{Modifier Name}' for naming all css classes. This is a shift from old BEM naming that can still be found in most SCSS files. Going forward we want to switch completely to ABEM since our design strategy follows atomic design guidelines. Example: For an input field atom, located in header with a smaller size, the css class would look something like this: a-header__search-input--small
Directory Structure / File Naming
Newly refactored components names should be kebab-case with granularity as ending i.e. {component-name}.{granularity}.scss . This helps in quick classifications of element and we can use IDE support to view atoms, molecules and organisms with desired file icons. Example: headline.atom.scss All newly refactored component should go under /styles/v2/components/.There is no decision on creating separate folders for atoms, molecules and organisms as yet. If you wish to do so, please make sure to move existing components to correct folders. It is also advisable to write media specific scss in separate files, this can help us load device specific styles on demand in future. In such cases the media breakpoint should be part of the file name. Example: header-xxl.atom.scss
Guidelines
- Atoms should not hold any sizing information outside their bounds e.g. padding, margins e.t.c. The size of an atom should be dictated solely be the direct parent using it i.e. the molecule or organism using it
- Avoid using domain specific naming in SCSS for components e.g. ‘a-checkout__header—logo’ rather use reusable generic names in the context of UI
- Don’t Introduce new helper CSS Classes.
- Don’t use hardcoded css values other than the global variables. If there is a new value/design token e.g. font size or color that is not previously used, discuss with design team and adapt the variables instead
- Only use ABEM selectors - Avoid tags, IDs or pseudo selectors at all costs
- Use separate files for separate media queries styles (See File Naming above)
- Always reflect all changes in class names in respective design system components
- A higher level component should not directly change styling of a lower level component. This means a molecule can not have styles or refrences of an atoms used inside it. In case of style changes, new atoms with modifiers should be introduced. For spacing and layouting the molecule should introduce its own class that is either added directly to the atom or to a container for atom inside that molecule.
Templating - twig
Directory Structure / File Naming
Similar to SCSS newly refactored components are kebab-case with granularity as ending i.e. {component-name}.{granularity}.twig . This helps in quick classifications of element and we can use IDE support to view atoms, molecules and organisms with desired file icons.
Example: headline.atom.twig
Components that are not specific to a domain should go under application folder: ProjectA/Yves/Application/Theme/boss/components. As we try to keep components as generic as possible, a majority of coponents should go there. However, for more specific components e.g. product-widgets e.t.c, use the component folder of appropriate bundle.
Guidelines
- Components should be completely agnostic to application logic and completely dumb. All logic or data rendered by a component should be passed down to it via parent as twig properties. This means that refrencing objects like `product.image` e.t.c. should not be done in components. See button.twig component for inspiration
- Do not use helpers classes in templates. Helpers classes(e.g. _p3, _m3, txt—bold) increase complexity and noise in UI. We want to stop using them completely and eventually remove them. If you want to make style changes create/update components with new styles instead. The only exception for using helpers is CMS pages
- Avoid creating new styles by compositing multiple css classes in twig. Similar to previous point, adding multiple classes to a component in twig to create a new styles creates noise and intransparency in UI. Instead try to keep one class per element e.g. instead of doing this `class=“txt—main txt—bold txt—grenn”`, create a new css class with a functional that has all the properties of those helpers.
- Don’t create duplicate templates for minor changes, instead update existing components to conditionally render different states based on information passed to it
- We use grid for lay outing and flex for layouts. Going forward try to using flexbox for layouts as much as possible to keep layouts fluid and help the mobile/desktop split in future.
Naming of component props
The naming should follow BEM naming convention but with camelCase. e.g. a flag for no padding in container should look like containerPaddingNone.
Prop name: elementPropertyValue
Boolean props: use Is instead of should e.g. isBuyButtonVisible.
Common understanding
Atoms
Atoms for us are the smallest possible functional units of UI. In terms of implementation, atoms are mostly directly mapped to a css class. However this does not mean that only single tag elements are atoms. Atoms can consist of multiple HTML tags as well. Unlike helpers/utility css classes, atom should serve a function in UI and should not be overly generic. The point of reference for all atoms, molecules and organisms should be the design team. When in doubt, check with design team.Example: A tooltip is an atom. Although it can have multiple html elements(container, text), there is no further functional breakdown possible for it and therefore is an atom.
Molecules
Molecules are components created using combination of atoms that are rather simple. Before refactoring/creating molecules, make sure you have atoms available so those could be used in molecules. . Example: Alerts, Quantity Widgets, Progress bars
Organisms
Organisms are components created using combination of molecules that are rather complex. Before refactoring/creating molecules, make sure you have molecules and atoms available so those could be used in molecules. . Example: Header, Footer, Pagination