Core

The core of the component library contains all settings, variables, mixins, reset css and our strongest base component: the grid system.

Installation

Vl-ui-core is automatically installed after intalling any NPM package.

                      
                        npm install @govflanders/vl-ui-core
                      
                    
                      
                        yarn add @govflanders/vl-ui-core
                      
                    

Usage

Import SASS

Vl-ui-core is always the first import in your scss file. Why is that?

                      
                        @import "vl-ui-core/src/scss/core";
                      
                    

Make sure your sass --include-path includes node_modules/@govflanders/.

ITCSS structure

To manage the codebase architecture, we follow the Inverted Triangle CSS principle from Lubos Kmetko. His blogpost on structuring CSS explains how to easily set up an extensive, dynamic and maintainable CSS front-end architecture.

  • Settings (vl-ui-core): used with preprocessors, contain fonts, color definitions, etc.
  • Tools (vl-ui-core):Β globally used mixins and functions. Note: do not output any CSS in the first 2 layers.
  • Generic (vl-ui-core): reset and/or normalize styles, box-sizing definitions, etc. This is the first layer that generates actual CSS.
  • Elements (vl-ui-core): styling for bare HTML elements (such as H1, A, etc.). These elements come with default styling from the browser, which we can redefine here.
  • Objects: class-based selectors that define undecorated design patterns, such as a media object known from OOCSS -- we don't style undecorated design patterns.
  • Components: these are specific UI components on which we work most. Our customize UI components are often composed of Objects and Components.
  • UtilitiesΒ (vl-ui-util): utilities and helper classes can override anything which precedes all other levels in the triangle, e.g. hide helper class.

Therefor core always comes first, components follow, utilities close the gate.

                      
                        // Core
                        @import "vl-ui-core/src/scss/core";

                        // Components
                        @import "vl-ui-alert/src/scss/alert";

                        // Utilities
                        @import "vl-ui-util/src/scss/util";
                      
                    

Make sure your sass --include-path includes node_modules/@govflanders/.

What's typically in a package

                      
                        .
                        β”œβ”€ package.json
                        β”œβ”€ README.md              -- Use the doc.html file instead
                        β”œβ”€ dist/
                        β”‚  β”œβ”€ doc.html            -- Same documentation as on the website, but locally
                        β”‚  β”œβ”€ index.html          -- Barebone component, use doc.html instead
                        β”‚  └─ js/
                        β”‚     β”œβ”€ accordion.js     -- Transpiled JS for your component (main module file in package.json)
                        β”‚     └─ accordion.min.js -- Transpiled & minified JS for your component
                        └─ src/
                           β”œβ”€ js/
                           β”‚  β”œβ”€ accordion.js     -- Raw ES6 Javascript
                           └─ scss/
                              └─ _accordion.scss  -- Raw SCSS to compile your component
                      
                    

The important bits

./src/scss/_{component-name}.scss

Include the base scss file in your setup to add the styling of the component.

./dist/js/{component-name}.js

Include the js file in your local build. The dist javascript is transpiled to ES5, so ready to use. Check out the javascript components on how to import and initialize them in your project.

./dist/html/doc.html

Shows you the documentation for that component. This is the same documentation that is rendered on this website.