Resa Design System

Appearance

Getting Started ​

This project uses this ViteJS boiler plate to witch we added the pre-processors SASS as explaned on this page.

First time running the project do this :

cmd
npm install

Then to run this localy with live reload do :

cmd
npm run dev

To be able to work with the last changes of the design system on your local env you'll need to do :

cmd
npm run preview

Naming Convention ​

IMPORTANT

The most important is that every name of any kind should be the most meaningful possible.

Styles ​

  • Files : start with "_" then camel case => _fileName.js
  • SASS variables : start with a $ then kebab case => $variable-name
  • SASS functions : kebab case => function-name
  • SASS mixins : kebab case => mixin-name
  • Classes :
    • Default : BEM naming with camel case => blockName__elementName--modifierName
  • CSS variables : Start with -- then kebab case => --prefix-group-variable-name
    • prefix => We prefix our CSS variables to make sure our variables are not in conflict with other projects. Here we chose ds for Design System.
    • group => This would be to be able to group variables by uses, for example : c for colors, bg for backgrounds, br for borders, etc.
    • Those are declared in the _root.scss file.

Scripts ​

  • Files :
    • Module : camel case => moduleName.js
    • Init Module : camel case => moduleName-init.js
  • Functions : camel case => functionName
  • variables :
    • DOM Elements : start with a "$" then camel case => $variableName
    • Constantes : upper snake case => CONSTANTE_NAME
    • Class : pascal case => VariableName
    • String : hungarian notation => sVariableName
    • Integer : hungarian notation => iVariableName
    • Boolean : hungarian notation => bVariableName
    • Array : hungarian notation => aVariableName
    • Object : hungarian notation => oVariableName
      • Object keys : camel case => { keyName: value }

SCSS files architecture ​

The architecture is inspired by this [Elad Shelchter's articles] on architecture

styles/
 |
 |- globals/            // Classes that are not specific for an element or component.
 |   |- ...
 |
 |- inits/              // Re-initialization of base styles
 |   |- normalize.scss
 |   |- reset.scss
 |
 |- partials/
 |   |- components/     // Components are elements grouped in one entity.
 |   |   |- ...         // A single style file per component.
 |   |- elements/       // Elements are smallest part of a page.
 |   |   |- ...         // A single style file per element.
 |
 |- utils/
 |   |- functions/      // Functions to be used in specific files and cases.
 |   |   |- ...
 |   |- mixins/         // Mixins to be used in specific files and cases.
 |   |   |- ...
 |   |- variables/      // Variables tools to be used in specific files and cases.
 |   |   |- ...
 |
 |- documentation.scss
 |- styles.scss         // Regroup every style files in one file

JS files architecture ​

To avoid loading all the script every time, we structure the script in modules with init to allow to load only the module needed on each page load.

script/
 |
 |- modules/
 |   |- module-name-init.js     // Dynamically import module if needed on page load
 |   |- module-name.js          // No import in those files, everything goes through the init
 |   |- ...
 |
 |- utils                       // Reusable functions, constants, etc...
 |   |- ...
 |
 |- script.js                     // Import all modules init
 |

GIT ​

Branches ​

  • dev/PDD-XXX => Developpement branches meant for new feature, fix or new components to be developpe. These branches are for local work only until they are tested, reviewed and merged to branch master. Then these branches have to be deleted.

  • master => This branch is the main branch and will never be deleted. All local changes that are tested, reviewed and validated are merged to this branch to be available in integration environments (qual, qta, integ, site, ...).

  • release => This branch is the final branch and will never be deleted. Once a release is ready, tested and validated on master, the branche is merged to release to be available to testing environments (qla, acc, uta, staging, preprod, ...)

Deployement ​

Only release branch will be deployed with specific versions number every time (the same way it's done for our API).

Triggering the build works as follows:

  • The master branch is updated (obligatory by a PR completed) => the build is launched and recreates the master links : http://dsgn.resa.be/master/style.css http://dsgn.resa.be/master/script.js
  • The release branch is updated (obligatory by a PR completed) => the build is launched and recreates the release links : http://dsgn.resa.be/release/style.css http://dsgn.resa.be/release/script.js
  • A tag is added manually at a particular stage of the release branch => the build is launched and creates the links based on this tag, for examples : http://dsgn.resa.be/0.0.1/style.css http://dsgn.resa.be/0.0.1/script.js