Hi there, Theme developer.

This npm package is a layer on top of ionic 2 to provide the styling of the Carrefour mobile application layout. It comes with a powerful and straightforward helper library to get you up and running in no time when you are styling pages.

1 ] INSTALL - You can use the theme in your ionic2 app or module like this:

• install the npm package in your project terminal

    npm i -save carrefour-theme

• Include the correct config file. See the config dir file in this repo, paste that in the project and load it up using npm like this:

    "config": {
        "ionic_sass": "./config/sass.config.js",
        "ionic_watch": "./config/watch.config.js"
    }

• Then you can use the carrefour scss in your _variables.scss or in other files:

    // =================================== //
    // BASIC IONIC VARIABLES //
    // =================================== //
    @import "ionic.theme.default";
  
    // =================================== //
    // THE CARREFOUR THEME //
    // =================================== //
    @import "carrefour"; // this is the theme layer import
  
    // =================================== //
    // EXTRA IONICONS //
    // =================================== //
    @import "ionicons";

2 ] USAGE - When you imported the Carrefour layer, you will be able to use and style many different components & html structures. Below you can find a list of all helpers, mixins, functions and components.

2.1 ] Variations (Helper classes)

located in utils/classes/... & Variation classes are prefixed with - sign and mostly based on the Emmet technique(see css section) naming convention. Feel free to create as many helpers you want.

• box-related.scss

The values below itterate from 0 to 15, and the exp factor is 5px. So 1 is 5px, 2 is 10px etc. You can adjust these 3 variables to have more capacity or larger gaps between the values. So all of the next classes should be suffixed with a value from 1 to 15. Examples: -w4, -mb10, -bdtlrs3, -hor-p5. Here is the list:

    * -w  => (width: ..;)
    * -h  => (height: ..;)
    * -lh  => (line-height: ..;)

    * -m  => (margin: ..;)
    * -mt / -mr / -mb / -ml  => (margin-top / margin-right / margin-bottom / margin-left)
    * -hor-m / -ver-m  => (margin-left & right / margin-top & bottom)

    * -p  => (padding: ..;)
    * -pt / -pr / -pb / -pl  => (padding-top / padding-right / padding-bottom / padding-left)
    * -hor-p / -ver-p  => (padding-left & right / padding-top & bottom)

    * -bdrs  => (border-radius: ..;)
    * bdtlrs / bdtrrs / bdblrs / bdbrrs => (border-top-left-radius / border-top-right-radius / border-bottom-left-radius / border-bottom-right-radius )

• c4-icons.scss

This file gives you the ability to create c4 icons and set the font sizes with extra helper classes. To create an icon use the i tag in combination with the c4-icon class and the icon class itself form the icon font doc or from the sandbox repo. Some examples:

    <i class="c4-icon icon-wishlist"></i> <== BASIC icon
    <i class="c4-icon icon-wishlist -ml1"></i> <== BASIC icon with a little margin on the left
    <i class="c4-icon c4-icon-xl icon-wishlist"></i> <== BASIC icon but with a larger icon
    <i class="c4-icon c4-icon-xl icon-wishlist -c-picton"></i> <== BASIC icon but with a larger icon and color picton
    
    <button ion-button icon-only menuToggle>
        <i class="c4-icon c4-icon-l icon-hamburger"></i>
    </button> <== BUTTON EXAMPLE with a large icon inside

    <button ion-button block color="endeavour">
        <i class="c4-icon c4-icon-xl -pl3 icon-livraison -abs-pull-left"></i>
        {{'shop.fav-store.buttons.home-delivery' | translate}}
        <i class="c4-icon c4-icon-xs -pr3 icon-arrow-right -abs-pull-right"></i>
    </button> <== BUTTON EXAMPLE with an icon left and an icon right with the abs-pull classes

• colors.scss

This is an expansion on the ionic color attribute technique. See the sassdoc for a list of all available colors in the colors map. This file lets you set colors and background colors on specific items. Together with a lighten or darken class. Some examples:

    <div class="-bgc-picton"></i> <== div with background color picton
    <p class="-c-endeavour">lorem</p> <== paragraph with color endeavour
    <p class="-c-endeavour -darken">lorem</p> <== paragraph with color endeavour darkened
    <p class="-c-endeavour -lighten">lorem</p> <== paragraph with color endeavour lightened
    <div class="-b-endeavour">lorem</div> <== div with 1px border color endeavour

• display.scss

This file lets you alter display settings on items. Some examples:

    AVAILABLE displays: none inline block list-item inline-list-item inline-block inline-table table table-cell table-column table-column-group table-footer-group table-header-group table-row table-row-group flex inline-flex grid inline-grid

    <p class="-display-i">lorem</p> <== sets the display on inline
    <p class="-display-n">lorem</p> <== sets the display on none
    <ul class="-display-flex">...</ul> <== sets the display on flex

• misc.scss

This file contains miscmiscellaneous helper classes from v1 (ionic 1) and some new helpers. Some examples:

    <div class="-fl-r"></div> <== float: right; on div element
    <div class="-fl-l"></div> <== float: left; on div element
    <div class="-fl-n"></div> <== float: none; on div element
    <div class="-fullwidth"></div> <== width: 100%; on div element
    <div class="-clean-last">
        <p></p>
        <p></p> <== margin-bottom: 0; to clean the margin on the last item
    </div>

• position.scss

This file contains positional helpers. Some examples:

    <button ion-button block color="endeavour">
        <i class="c4-icon c4-icon-xl -pl3 icon-livraison -abs-pull-left"></i> <== pulls this icon to the left of its parent can be combined with -p classes
    </button>

    <div class="-abs"></div> <== div with position: absolute;
    <div class="-rel"></div> <== div with position: relative;

• shapes.scss

This file contains shape helpers. To make 2 kind of circles. Some examples:

    <div class="-c4-circle3"></div> <== This uses flexbox to align the elements inside, best used with position absolute. and based on the itteration of 0 to 15 like with the box-related helpers.
    <div class="circle circle--s"></div> <== This creates a circle component, sets display inline block and can be combined with sx s m l and xl classes.

• typography.scss

This file contains typography helpers. All that is text related. it also itterates over the font sizes and the font families. Some examples:

    <p class="-ta-c">Lorem</p> <== text-align: center;
    <p class="-ta-l">Lorem</p> <== text-align: left;
    <p class="-ta-r">Lorem</p> <== text-align: right;
    <p class="-ta-j">Lorem</p> <== text-align: justify;
    <p class="-tt-u">Lorem</p> <== text-transform: uppercase;
    <p class="-tt-l">Lorem</p> <== text-transform: lowercase;
    <p class="-tt-n">Lorem</p> <== text-transform: none;
    <p class="-td-u">Lorem</p> <== text-decoration: underline;
    <p class="-td-lt">Lorem</p> <== text-decoration: line-trough;
    <p class="-td-n">Lorem</p> <== text-decoration: none;
    <p class="-ff-omnes-b">Lorem</p> <== font-family: "omnes_carrefoursemibold", "Helvetica Neue", "Roboto", sans-serif;
    <p class="-ff-arial">Lorem</p> <== font-family: "Arial";
    <p class="-fsz-xs">Lorem</p> <== font-size: .800rem; See sasdoc for variables.

2.2 ] Mixins

located in utils/mixins/... & Documented in sassdoc.

2.3 ] Variables

located in utils/variables/... & Documented in sassdoc.

2.4 ] Functions

located in utils/functions/... & Documented in sassdoc.

2.5 ] Base styles

located in base/.... These are the base styles for the app, it takes care of some ionic overriding and sets a basic vertical rhythm. These styles also add some additional classes to normal html tags.

3] BEST PRACTICES & Faqs

BE(V)M COMPONENTS

simplified SMACSS

IONIC OVERRIDES

OVERAL STRUCTURE AND LINTING ( keeping things clean)

When should I use a components and put its styling inside it and not use the variations?

Why is there a strange overriding (ion-app .show-page, ion-app .app-root {) at every helper file?

Why are all these ionic overrides available? And how do they correlate to the framework?

!IMPORTANT - The doc is currently under constant development. For now ask [email protected] for more info on some of the subjects.