# Core M&S reusable components/modules/templates
the above naming conventions follow the M&S pattern library (see http://patternlibrary.mnsdigital.io/#/Core)
distribution code is located at lib/assets/dist
- javascript is exposed as UMD (default) AMD and CommonJS modules and minified files are available for each.
- CSS is exposed as *-all.css for all devices or broken down into device size specific css files so adaptive or responsive behaviour can be implemeted.
- HTML mark up for AEM components can be found in the examples folder.
source code is located at lib/mns-core-ui
where you can find SASS and ES6 that generates the distribution files at build (and publish) time.
Tasks
gulp serve
will serve dev environmentgulp build
will compile assets to lib/assets/dist foldernpm test
will run all testsgulp test-unit
gulp test-visual
gulp lint-sass
gulp eslint
Core M&S Sass, fonts and images
Consuming the Library
The library exposes the following paths:
- sassPaths
- assetPaths
- assetImagePaths
- assetFontPaths
Install the module:
npm install mns-core-ui --save
Add the following to the gulp sass compile file.
var fearCoreUI = require('mns-core-ui');
.pipe(sass({
includePaths: fearCoreUI.sassPaths
})
);
The following variables need to be set
$mns-core-ui-font-dir: '/assets/fonts';
$mns-core-ui-images-dir: '/assets/images';
Copy mns-core-ui assets to your working directory
var fearCoreUI = require('mns-core-ui');
gulp.task('copy-mns-core-ui-assets', function() {
return gulp.src([fearCoreUI.assetPaths + '/**/*.*'])
.pipe(gulp.dest('/assets'));
});
Note that the variables set in step 3 should correspond to the location of the assets copied in step 4.
You can now reference any sass file.
(N.B it is a little confusing as the module has been renamed to mns-core-ui but internally the word fear is still used, these internal references will be changed in a release in the near future)
example:
@import 'fear-core-ui/base';
@import 'fear-core-ui/typography';
Basic Structure
fear-core-ui/base
contains all the variables, functions and mixins in the library.
You can import this multiple times in your SASS code.
fear-core-ui/extends
contains all the extends rules.
This should be imported once and ONLY once per generated CSS file. If you import it more than once per generated CSS file you will have duplicate CSS rules.
SASS / CSS coding standards
We want to make sure that unnecessary CSS is not imported to consuming projects.
Aggregates
The following can be exposed through aggregate files:
- mixins
- variables
- functions
Example:
@import utlities.scss;
@import 'utilities/functions';
@import 'utilities/mixins';
@import 'utilities/variables';
This can be done because the sass code in these files do not add CSS unless mixins / extends are explicitly called from the consuming code.
Explicit imports
When a sass file contains direct CSS it needs to consumed through an explicit import.
i.e. If I only wanted to use the buttons.sass
component. Importing an aggregate components.sass
which included all the components CSS. That would create bloat and unused CSS being included in the consuming project.
Example: The buttons components contains direct CSS and must be imported through a direct import and not an aggregate sass file.
@import ui-pattern/buttons;
.btn--primary {
@include create-btn(40px, 15px, $color__brand--green, $color__brand--dark-grey, $color__brand--background-grey, $color__brand--light-grey);
}
.btn--secondary {
@include create-btn(40px, 15px, $color__brand--grey-40, $color__brand--dark-grey, $color__brand--background-grey, $color__brand--light-grey);
}
Directory structure
assets
|- fonts
|- images
sass
Directory pattern
item.scss
- item // directory
|- _variables.scss
|- _extends.scss
|- _functions.scss
|- _mixins.scss
|- _module_itemA.scss
|- _module_itemB.scss
item.scss
@import 'item/variables';
@import 'item/extends';
@import 'item/functions';
@import 'item/mixins';
@import 'item/module_itemA';
@import 'item/module_itemB';
Directory categories
|- layouts
|- _grid.scss
|- grid
|- _variables.scss
|- _mixins.scss
|- _module_grid.scss
|- _zindex.scss
|- normalize
|- _module_mns-normalize.scss
|- _module_normalize.scss
|- typography
|- ui-pattern
|- _buttons.scss
|- buttons
|- _mixins.scss
|- _module_icons.scss
|- _module_buttons.scss
|- utilites
|- _mixins_measurements.scss
_colors.scss
_sprites.scss
_normalize.scss
Add an icon to the mns-icon fonts
The mns-icons fonts are located in the lib/assets/fonts
directory. The font directory contains the generated mns-icon fonts:
- mns-icons.eot
- mns-icons.svg
- mns-icons.ttf
- mns-icons.woff
In the mns-icons
folder you will find the settings file (selection.json
) used by icomoon and a demo project to serve up and test the fonts:
The following steps will guide you through the process of adding icons to the mns-icon font
- Browse to https://icomoon.io/app/
- Click on Import Icons
- Browse to the mns-core-ui project folder and select the selection.json file (
lib/assets/fonts/mns-icons/selection.json
) - If a message dialog pops up select to import all settings from the file
- Select the required fonts from the UI
- When you are done, at the bottom click
Generate Font
- Check if the old icons unicode signatures match with the original font (you can achieve this by serving up the
demo.html
file in the demo-files folder. - Click download and save the zip file on your local hard drive
- Unzip this folder and copy the generated font files to
lib/assets/fonts
and the demo files to themns-icons
folder - Add the icons unicode sign to the following file:
lib/sass/mns-core-ui/ui-pattern/_extends_content.scss
and give it a proper sass variable name - Generate the css class in the
lib/sass/mns-core-ui/ui-pattern/_module_icons.scss
file:scss @include('css-class-name', 'icon-variable-name')
Linting
npm test
runs eslint eslint tasks
and sass lint gulp lint-sass
Further reading
# mns-core-ui change log
5.0.4
- remove rewrite rules for dev environment and use GET params directly
5.0.3
- [bugfix] normalise elements not capturing all scenarios got getElementById and querySelectorAll
5.0.1
- add the eot font file extension for the london fonts
5.0.0
- rename module fear-core-ui -> mns-core-ui
4.1.3
- update tests and fear-core-aut to version v4.0.0
4.1.0
- add (global) navigation template
- add application data module to make application config data available to modules/templates
- implement es6 transpiling/JS minification/SASS compilation to expose assets
- add JSdoc for mns-core-ui javascript
4.0.2
- hide accessibility text from left instead of top
4.0.1
- new font assets - fixes 1/2 and 1/4 reversal
4.0.0
- removed helvetica fonts and no longer used fonts (Breaking)
- added new fonts mns-london, mns-london-bold and mns-london-light (Feature)
- Added 3 Sparks icons (offers, events, priority access) as mns-icons font (Feature)
3.0.0
- Refactor sprites to prevent duplication. (Breaking)
- Added Sparks logo as mns-icons font (Feature)
- Refactor tooltip (Patch)
2.0.0
- improved more logical folder structure
- Finalised MNS-london regular and bold fonts.
1.1.11
- Aligning with the UX team on which of the mns-london fonts we should use:
- mns-london-regular - the semibold font (much better legibility)
- mns-london-demibold - the bold font (used is font-weight: bold produces inconsistent results)
- add ux tooltip styles
- add fear-core dev sass and eslint
1.1.10
- Fixing path to the newly included MNS-london fonts (oops)
1.1.9
- Including the updated MNS-london regular and bold fonts
1.1.8
- Install sassdoc-theme-mns from github using SSH, as repo is now private
1.1.7
- Added new icons
- icon-circle-arrow e902
- icon-long-arrow e900
- icon-gear e903
- icon-gear-filled e904
- icon-lock e905
- icon-circle-arrow e902
1.1.6
- Fix bug for sparks icons
1.1.5
- Screen sm breakpoint fix
- added icon-sparks-filled to icon.scss
1.1.4
- add button icon with left arrow
1.1.3
- added 'sparks-filled' icon
Contributing
Here's the most direct way to get your work merged into the project:
If your work is a new feature or a patch then follow the following workflow
- Fork the project.
- Clone down your fork (
git clone git@github.com:[username]/mns-core-ui.git
). - Create a topic branch to contain your change (
git checkout -b my_awesome_feature
). - Code away and add tests if applicable. Not necessarily in that order.
- Make sure everything still passes by running
npm run test
. - Update the change log with details of the change under the corresponding heading (new feature/patch) - create the heading if it doesnt already exist. The version of the next published version will then be decided by this.
- If necessary, rebase your commits into logical chunks, without errors.
- Push the branch up (
git push origin my_awesome_feature
). - Create a pull request against mns-core-ui/master and describe what your change does and the why you think it should be merged.
If your work is a breaking change please come to talk to the core team before commencing development.